Prompt with a single prompt object. Returns an object with the response.
const prompts = require('prompts');(async () => { const 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 an object with the responses.
Make sure to give each prompt a unique name property to prevent overwriting values.
const prompts = require('prompts');const 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?' }];(async () =>
Dynamic Prompts
Prompt properties can be functions too.
Prompt Objects with type set to falsy values are skipped.
Prompter function which takes your prompt objects and returns an object with responses.
prompts
Type: Array|Object
Array of prompt objects.
These are the questions the user will be prompted. You can see the list of supported prompt types here.
Prompts can be submitted (return, enter) or canceled (esc, abort, ctrl+c, ctrl+d). No property is being defined on the returned response object when a prompt is canceled.
options.onSubmit
Type: Function
Default: () => {}
Callback that's invoked after each prompt submission.
Its signature is (prompt, answer, answers) where prompt is the current prompt object, answer the user answer to the current question and answers the user answers so far. Async functions are supported.
Return true to quit the prompt chain and return all collected responses so far, otherwise continue to iterate prompt objects.
Callback that's invoked when the user cancels/exits the prompt.
Its signature is (prompt, answers) where prompt is the current prompt object and answers the user answers so far. Async functions are supported.
Return true to continue and prevent the prompt loop from aborting.
On cancel responses collected so far are returned.
Programmatically inject responses. This enables you to prepare the responses ahead of time.
If any injected value is found the prompt is immediately resolved with the injected value.
This feature is intended for testing only.
values
Type: Array
Array with values to inject. Resolved values are removed from the internal inject array.
Each value can be an array of values in order to provide answers for a question asked multiple times.
If a value is an instance of Error it will simulate the user cancelling/exiting the prompt.
Prompts Objects are JavaScript objects that define the "questions" and the type of prompt.
Almost all prompt objects have the following properties:
{ type: String | Function, name: String | Function, message: String | Function, initial: String | Function | Async Function format: Function | Async Function, onRender: Function onState: Function stdin: Readable stdout: Writeable}
Each property be of type function and will be invoked right before prompting the user.
The function signature is (prev, values, prompt), where prev is the value from the previous prompt,
values is the response object with all values collected so far and prompt is the previous prompt object.
Function example:
{ type: prev => prev > 3 ? 'confirm' : null, name: 'confirm', message: (prev, values) => `Please confirm that you eat ${values.dish} times ${prev} a day?`}
The above prompt will be skipped if the value of the previous prompt is less than 3.
type
Type: String|Function
Defines the type of prompt to display. See the list of prompt types for valid values.
If type is a falsy value the prompter will skip that question.
{ type: null, name: 'forgetme', message: `I'll never be shown anyway`,}
name
Type: String|Function
The response will be saved under this key/property in the returned response object.
In case you have multiple prompts with the same name only the latest response will be stored.
Make sure to give prompts unique names if you don't want to overwrite previous values.
message
Type: String|Function
The message to be displayed to the user.
initial
Type: String|Function
Optional default prompt value. Async functions are supported too.
format
Type: Function
Receive the user input and return the formatted value to be used inside the program.
The value returned will be added to the response object.
The function signature is (val, values), where val is the value from the current prompt and
values is the current response object in case you need to format based on previous responses.
Callback for when the prompt is rendered.
The function receives kleur as its first argument and this refers to the current prompt.
Example:
{ type: 'number', message: 'This message will be overridden', onRender(kleur) { this.msg = kleur.cyan('Enter a number'); }}
onState
Type: Function
Callback for when the state of the current prompt changes.
The function signature is (state) where state is an object with a snapshot of the current state.
The state object has two properties value and aborted. E.g { value: 'This is ', aborted: false }
stdin and stdout
Type: Stream
By default, prompts uses process.stdin for receiving input and process.stdout for writing output.
If you need to use different streams, for instance process.stderr, you can set these with the stdin and stdout properties.
Hit tab to autocomplete to initial value when provided.
Example
{ type: 'text', name: 'value', message: `What's your twitter handle?`}
Options
Param
Type
Description
message
string
Prompt message to display
initial
string
Default string value
style
string
Render style (default, password, invisible, emoji). Defaults to default
format
function
Receive user input. The returned value will be added to the response object
validate
function
Receive user input. Should return true if the value is valid, and an error message String otherwise. If false is returned, a default error message is shown
onRender
function
On render callback. Keyword refers to the current prompt
This prompt is a similar to a prompt of type 'text' with style set to 'password'.
Example
{ type: 'password', name: 'value', message: 'Tell me a secret'}
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
validate
function
Receive user input. Should return true if the value is valid, and an error message String otherwise. If false is returned, a default error message is shown
onRender
function
On render callback. Keyword this refers to the current prompt
onState
function
On state change callback. Function signature is an object with two properties: and
Receive user input. The returned value will be added to the response object
validate
function
Receive user input. Should return true if the value is valid, and an error message String otherwise. If false is returned, a default error message is shown
onRender
function
On render callback. Keyword this refers to the current prompt
onState
function
On state change callback. Function signature is an object with two properties: and
You can type in numbers and use up/down to increase/decrease the value. Only numbers are allowed as input. Hit tab to autocomplete to initial value when provided.
Example
{ type: 'number', name: 'value', message: 'How old are you?', initial: 0, style: 'default', min: 2, max: 10}
Options
Param
Type
Description
message
string
Prompt message to display
initial
number
Default number value
format
function
Receive user input. The returned value will be added to the response object
validate
function
Receive user input. Should return true if the value is valid, and an error message String otherwise. If false is returned, a default error message is shown
Receive user input. The returned value will be added to the response object
hint
string
Hint to display to the user
warn
string
Message to display when selecting a disabled option
choices
Array
Array of strings or choices objects [{ title, description, value, disabled }, ...]. The choice's index in the array will be used as its value if it is not specified.
Interactive multi-select prompt.
Autocomplete is a searchable multiselect prompt with the same options. Useful for long lists.
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.
Receive user input. The returned value will be added to the response object
instructions
string or boolean
Prompt instructions to display
choices
Array
Array of strings or choices objects [{ title, value, disabled }, ...]. The choice's index in the array will be used as its value if it is not specified.
optionsPerPage
number
Number of options displayed per page (default: 10)
min
number
Min select - will display error
max
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.
The prompt will list options based on user input. Type to filter the list.
Use ⇧/⇩ to navigate. Use tab to cycle the result. Use Page Up/Page Down (on Mac: fn + ⇧ / ⇩) to change page. 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.
Use left/right/tab to navigate. Use up/down to change date.
Example
{ type: 'date', name: 'value', message: 'Pick a date', initial: new Date(1997, 09, 12), validate: date => date > Date.now() ? 'Not in the future' : true}
Options
Param
Type
Description
message
string
Prompt message to display
initial
date
Default date
locales
object
Use to define custom locales. See below for an example.
mask
string
The format mask of the date. See below for more information. Default: YYYY-MM-DD HH:mm:ss
validate
function
Receive user input. Should return true if the value is valid, and an error message String otherwise. If false is returned, a default error message is shown
onRender
function
On render callback. Keyword this refers to the current prompt