⚠️ Ink Scroll Prompts is experimental. The API is not stable!

Ink Scroll Prompts

Prompts that scroll. Using ink. 🎉

ink-scroll-prompts enables you to display and interact with strings of large or unknown length. It was build to implement a REPL that could suggest code snippets mined from NPM package documentation. It's an alternative to existing prompt packages, or full screen curses apps which use the alternate screen buffer. ink-scroll-prompts preserves the terminal history for more traditional command line interfaces.

Install

You can install ink-scroll-prompts using npm:

npm install ink-scroll-prompts

Usage

You can run an Input prompt using:

const {Input} = require("ink-scroll-prompts");

var prompt = new Input({
    prefix: "Write something",
    seperator: "!",
    multiline: true,
});

prompt.run()
    .then(response =>console.log("You wrote: " + response))
    .catch(e => {})

Full Example

Or, use the components and ink for advanced UIs!

See the examples folder for more usage examples.

Prompts

Input

An input prompt, extending Prompt. It implements a HandledInputPrompt.

Options

Accepts all HandledInputPrompt properties.

heightOffset

Default 1. Adjust the maxHeight of the component, if you want previous terminal lines to always be visable.

Select

A prompt for selecting from a list, extending Prompt. It implements a SelectComponent.

const {Select} = require("ink-scroll-prompts");

async function main(){
    var prompt = new Select({
        message: "Save and exit?",
        items: ["Save and exit", "Exit without saving", "Cancel"]
    });

    var result = await prompt.run();
}

Full Example

Options

Accepts all SelectComponent properties.

message

Type : string

A single line message string to display above the list. This string truncates if it is too big to be displayed. Future support for multilines may be possible when ink supports a maxHeight property.

items

Type : array

An array of strings to display as options. You may also pass an array of objects with a label field.

heightOffset

Type : number

Default 1. Adjust the maxHeight of the component, if you want previous terminal lines to always be visable.

Components

InputPrompt

An input prompt, which can be used to accept text input, provide completions and suggestions.

ink.render(e(Inputprompt, properties));

Properties

initialText

Type : string

Set an initial input string.

placeholder

Type : string

Set a placeholder string that appears when input is empty.

completions

Type : Array<string>

Array of string completions that display inline at the end of input as you type.

complete

Type : function(input : string, lastWord : string, cursor : number, completions : Array<String>) : string

Custom complete function. Returns a string match.

multiline

Type : boolean

Allow user to insert a newline using cursorDown on last line. Default false.

Initial input and copy-pasted input can still include newlines.

disableNewLines

Type : boolean

If multiline is false, disable newlines in input. This enforces no newlines in initial input and copy pasted input. Default false.

newlineOnDown

Type : boolean

If multiline is true, disable newlines on cursor down. Useful if mapping newline to a specific key, see the editor prompt example.

accentColor

Type : string

The accent colour, a string recognized by ink and chalk. Default: cyan.

footer

Type : boolean

To display a footer. Default: false.

footerMessage

Type : string | React.element

Message to display in footer, or, if you supply a custom element, this overwrites the default footer.

header

Type : string | React.element

Single line of text to display above input, or, a custom element.

HandledInputPrompt

An InputPrompt that implements ink.useInput for you. It accepts all of InputPrompt's properties.

ink.render(e(HandledInputprompt, properties));

Properties

useDefaultKeys

Type : boolean

If HandledInputPrompt should use the default keybindings defined at InputPrompt.DefaultKeyBindings. Default: true.

additionalKeys

Type : object

Supply custom keybindings. If useDefaultKeys is false, this will be the only keybindings, if true, it will only be combined with existing keys. To overwrite keybindings, set useDefaultKeys false, and supply a modified copy of InputPrompt.DefaultKeyBindings here.

InputBox

And Input Box is the base component for accepting and navigating text input.

Keybindings

While you can create your own components that handle input, each component already has a handled version with default handling.

KeyBinding	Command	Details
return	Submit
escape	Cancel
delete	Delete Character
meta + delete	Delete word	ctrl + w also works.
ctrl + delete	Delete line	ctrl + u also works. See issue.
ctrl + ←	Move to line start	See issue.
ctrl + ➞	Move to line end	See issue.
meta + ←	Previous Word	meta + b also works. See issue.
meta + ➞	Next word	meta + f also works. See issue.
↑	Cursor Line Up
↓	Cursor Line Down

meta is equivalent to Alt on Windows and Option on Mac. You may need to enable the use of Option as Meta on Mac.

Testing

This project uses mocha and nyc to test. You can run the tests using:

npm test

npm run coverage

To test, this project uses a non-exported patch of ink-testing-library available here that uses the neccessary fork, however, this will be removed when no longer necessary. The test-utils file also contains functions used to test components. For testing your own code, I recommend copying these files into your project.

License

Unlicense. Do what you want with it. ❤️

This file was automatically generated.