Lightweight, beautiful and user-friendly interactive prompts >_ Easy to use CLI prompts to enquire users for information▌
```js
const prompts = require('prompts');
const response = await prompts({
type: 'number',
name: 'value',
message: 'How old are you?'
});
console.log(response); // => { value: 23 }
```
> Examples are meant to be illustrative. `await` calls need to be run within an async function. See [`example.js`](https://github.com/terkelg/prompts/blob/master/example.js).
## ❯ Examples
### Single Prompt
Prompt with a single prompt object. Returns object with the response.
```js
const prompts = require('prompts');
let response = await prompts({
type: 'text',
name: 'meaning',
message: 'What is the meaning of life?'
});
console.log(response.meaning);
```
### Prompt Chain
Prompt with a list of prompt objects. Returns object with response.
Make sure to give each prompt a unique `name` property to prevent overwriting values.
```js
const prompts = require('prompts');
let questions = [
{
type: 'text',
name: 'username',
message: 'What is your GitHub username?'
},
{
type: 'number',
name: 'age',
message: 'How old are you?'
},
{
type: 'text',
name: 'about',
message: 'Tell something about yourself',
initial: 'Why should I?'
}
];
let response = await prompts(questions);
// => response => { username, age, about }
```
### Dynamic Prompts
Prompt properties can be functions too.
Prompt Objects with `type` set to `falsy` values are skipped.
```js
const prompts = require('prompts');
let questions = [
{
type: 'text',
name: 'dish',
message: 'Do you like pizza?'
},
{
type: prev => prev == 'pizza' ? 'text' : null,
name: 'topping',
message: 'Name a topping'
}
];
let response = await prompts(questions);
```
## ❯ API
### prompts(prompts, options)
Type: `Function`
```js
{
type: 'text',
name: 'value',
message: `What's your twitter handle?`,
style: 'default',
initial: ''
}
```
#### Options
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| message | string | | Prompt message to display |
| initial | string | '' | Default string value |
| style | string | 'default' | Render style (`default`, `password`, `invisible`) |
| format | function | | Receive user input. The returned value will be added to the response object |
| onState | function | | On state change callback |
### password(message, [initial])
> Password prompt with masked input.
This prompt is a similar to a prompt of type `'text'` with `style` set to `'password'`.
#### Example
```js
{
type: 'password',
name: 'value',
message: 'Tell me a secret',
initial '',
}
```
#### Options
| Param | Type | Description |
| --- | --- | --- |
| message | string | Prompt message to display |
| initial | string | Default string value |
| format | function | Receive user input. The returned value will be added to the response object |
| onState | function | On state change callback |
### invisible(message, [initial])
> Prompts user for invisible text input.
This prompt is working like `sudo` where the input is invisible.
This prompt is a similar to a prompt of type `'text'` with style set to `'invisible'`.
#### Example
```js
{
type: 'invisible',
name: 'value',
message: 'Enter password',
initial: ''
}
```
#### Options
| Param | Type | Description |
| --- | --- | --- |
| message | string | Prompt message to display |
| initial | string | Default string value |
| format | function | Receive user input. The returned value will be added to the response object |
| onState | function | On state change callback |
### number(message, initial, [max], [min], [style])
> Prompts user for number input.
You can type in numbers and use up/down to increase/decrease the value. Only numbers are allowed as input.
#### Example
```js
{
type: 'number',
name: 'value',
message: 'How old are you?',
initial: 0,
style: 'default',
min: 2,
max: 10
}
```
#### Options
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| message | string | | Prompt message to display |
| initial | number | `null` | Default number value |
| format | function | | Receive user input. The returned value will be added to the response object |
| max | number | `Infinity` | Max value |
| min | number | `-infinity` | Min value |
| style | string | 'default' | Render style (`default`, `password`, `invisible`) |
| onState | function | | On state change callback |
### confirm(message, [initial])
> Classic yes/no prompt.
Hit y or n to confirm/reject.
#### Example
```js
{
type: 'confirm',
name: 'value',
message: 'Can you confirm?',
initial: true
}
```
#### Options
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| message | string | | Prompt message to display |
| initial | boolean | false | Default value |
| format | function | | Receive user input. The returned value will be added to the response object |
| onState | function | | On state change callback |
### list(message, [initial])
> List prompt that return an array.
Similar to the `text` prompt, but the output is an `Array` containing the
string separated by `separator`.
```js
{
type: 'list',
name: 'value',
message: 'Enter keywords',
initial: '',
separator: ','
}
```
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| message | string | | Prompt message to display |
| initial | boolean | false | Default value |
| format | function | | Receive user input. The returned value will be added to the response object |
| separator | string | ',' | String separator. Will trim all white-spaces from start and end of string |
| onState | function | | On state change callback |
### toggle(message, [initial], [active], [inactive])
> Interactive toggle/switch prompt.
Use tab or arrow keys/tab/space to switch between options.
#### Example
```js
{
type: 'toggle',
name: 'value',
message: 'Can you confirm?',
initial: true,
active: 'yes',
inactive: 'no'
}
```
#### Options
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| message | string | | Prompt message to display |
| initial | boolean | false | Default value |
| format | function | | Receive user input. The returned value will be added to the response object |
| active | string | 'on' | Text for `active` state |
| inactive | string | 'off' | Text for `inactive` state |
| onState | function | | On state change callback |
### select(message, choices, [initial])
> Interactive select prompt.
Use up/down to navigate. Use tab to cycle the list.
#### Example
```js
{
type: 'select',
name: 'value',
message: 'Pick a color',
choices: [
{ title: 'Red', value: '#ff0000' },
{ title: 'Green', value: '#00ff00' },
{ title: 'Blue', value: '#0000ff' }
],
initial: 1
}
```
#### Options
| Param | Type | Description |
| --- | --- | --- |
| message | string | Prompt message to display |
| initial | number | Index of default value |
| format | function | Receive user input. The returned value will be added to the response object |
| choices | Array | Array of choices objects `[{ title, value }, ...]` |
| onState | function | On state change callback |
### multiselect(message, choices, [initial], [max], [hint])
> Interactive multi-select prompt.
Use space to toggle select/unselect and up/down to navigate. Use tab to cycle the list. You can also use right to select and left to deselect.
By default this prompt returns an `array` containing the **values** of the selected items - not their display title.
#### Example
```js
{
type: 'multiselect',
name: 'value',
message: 'Pick colors',
choices: [
{ title: 'Red', value: '#ff0000' },
{ title: 'Green', value: '#00ff00' },
{ title: 'Blue', value: '#0000ff', selected: true }
],
initial: 1,
max: 2,
hint: '- Space to select. Return to submit'
}
```
#### Options
| Param | Type | Description |
| --- | --- | --- |
| message | string | Prompt message to display |
| format | function | Receive user input. The returned value will be added to the response object |
| choices | Array | Array of choices objects `[{ title, value, [selected] }, ...]` |
| max | number | Max select |
| hint | string | Hint to display user |
| onState | function | On state change callback |
This is one of the few prompts that don't take a initial value.
If you want to predefine selected values, give the choice object an `selected` property of `true`.
### autocomplete(message, choices, [initial], [suggest], [limit], [style])
> Interactive auto complete prompt.
The prompt will list options based on user input. Type to filter the list.
Use up/down to navigate. Use tab to cycle the result. Hit enter to select the highlighted item below the prompt.
The default suggests function is sorting based on the `title` property of the choices.
You can overwrite how choices are being filtered by passing your own suggest function.
#### Example
```js
{
type: 'autocomplete',
name: 'value',
message: 'Pick your favorite actor',
choices: [
{ title: 'Cage' },
{ title: 'Clooney', value: 'silver-fox' },
{ title: 'Gyllenhaal' },
{ title: 'Gibson' },
{ title: 'Grant' },
]
}
```
#### Options
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| message | string | | Prompt message to display |
| format | function | | Receive user input. The returned value will be added to the response object |
| choices | Array | | Array of auto-complete choices objects `[{ title, value }, ...]` |
| suggest | function | By `title` string | Filter function. Defaults to sort by `title` property. `suggest` should always return a promise |
| limit | number | 10 | Max number of results to show |
| style | string | `'default'` | Render style (`default`, `password`, `invisible`) |
| onState | function | | On state change callback |
Example on what a `suggest` function might look like:
```js
const suggestByTitle = (input, choices) =>
Promise.resolve(choices.filter(i => i.title.slice(0, input.length) === input))
```
## ❯ Credit
Many of the prompts are based on the work of [derhuerst](https://github.com/derhuerst).
## ❯ License
MIT © [Terkel Gjervig](https://terkel.com)