ink-scroll-prompts v0.1.0
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 => {})
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();
}
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.