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:
```sh
npm install ink-scroll-prompts
```
## Usage
You can run an `Input` prompt using:
```js
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](/examples/prompts/input.js)*
Or, use the components and ink for advanced UIs!
See the [examples](/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`.
```js
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](/examples/prompts/select.js)*
#### 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.
```js
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`
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`
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](/examples/components/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.
```js
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](https://github.com/Brittany-Reid/ink-scroll-prompts/issues/1).|
| ctrl + ← | Move to line start | See [issue](https://github.com/Brittany-Reid/ink-scroll-prompts/issues/2).|
| ctrl + ➞ | Move to line end | See [issue](https://github.com/Brittany-Reid/ink-scroll-prompts/issues/2).|
| meta + ← | Previous Word | meta + b also works. See [issue](https://github.com/Brittany-Reid/ink-scroll-prompts/issues/3). |
| meta + ➞ | Next word | meta + f also works. See [issue](https://github.com/Brittany-Reid/ink-scroll-prompts/issues/3). |
| ↑ | 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:
```sh
npm test
```
```
npm run coverage
```
To test, this project uses a non-exported patch of `ink-testing-library` available [here](/src/patch/ink-testing-library.js) that uses the neccessary fork, however, this will be removed when no longer necessary. The [test-utils](/src/test-utils.js) 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.*
---
_Source: https://npm.io/package/ink-scroll-prompts · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
