prompts

What is prompts?

The 'prompts' npm package is a lightweight, beautiful, and user-friendly command-line prompts library. It helps developers create interactive command-line interfaces (CLIs) with ease. It supports various types of input, validation, and conditional prompts.

What are prompts's main functionalities?

Text Input

This feature allows for simple text input. The user is prompted to enter their name, and the input is then greeted.

const prompts = require('prompts');

(async () => {
  const response = await prompts({
    type: 'text',
    name: 'name',
    message: 'What is your name?'
  });

  console.log(`Hello, ${response.name}!`);
})();

Password Input

This feature is for password input where the input is masked. The user is prompted to enter a password without displaying it on the screen.

const prompts = require('prompts');

(async () => {
  const response = await prompts({
    type: 'password',
    name: 'password',
    message: 'Enter your password'
  });

  console.log(`Your password is ${response.password}`);
})();

Number Input

This feature allows for number input. The user is prompted to enter their age, and the input is then confirmed.

const prompts = require('prompts');

(async () => {
  const response = await prompts({
    type: 'number',
    name: 'age',
    message: 'How old are you?'
  });

  console.log(`You are ${response.age} years old.`);
})();

Confirmation

This feature is for yes/no confirmation prompts. The user is asked to confirm, and the response is a boolean.

const prompts = require('prompts');

(async () => {
  const response = await prompts({
    type: 'confirm',
    name: 'confirm',
    message: 'Can you confirm?'
  });

  console.log(`You ${response.confirm ? 'confirmed' : 'did not confirm'}.`);
})();

Choice Selection

This feature allows users to select from a list of choices. The user is prompted to pick a color from a list, and the selected value is then displayed.

const prompts = require('prompts');

(async () => {
  const response = await prompts({
    type: 'select',
    name: 'color',
    message: 'Pick a color',
    choices: [
      { title: 'Red', value: '#ff0000' },
      { title: 'Green', value: '#00ff00' },
      { title: 'Blue', value: '#0000ff' }
    ]
  });

  console.log(`You picked ${response.color}`);
})();

Multiple Selection

This feature allows users to select multiple items from a list. The user is prompted to select fruits, and the selected values are then displayed.

const prompts = require('prompts');

(async () => {
  const response = await prompts({
    type: 'multiselect',
    name: 'fruits',
    message: 'Select fruits',
    choices: [
      { title: 'Apple', value: 'apple' },
      { title: 'Orange', value: 'orange' },
      { title: 'Pear', value: 'pear' }
    ]
  });

  console.log(`You selected ${response.fruits.join(', ')}`);
})();

Other packages similar to prompts

inquirer

Inquirer.js is a common interactive command-line user interfaces library. It is more feature-rich and extensible than 'prompts', offering a wider variety of question types and more complex interactions, but it is also heavier.

enquirer

Enquirer is a stylish CLI prompts library. It is similar to 'prompts' but offers more prompt types and is more customizable. It is designed with performance in mind and is suitable for applications requiring a high degree of user interaction.

readline-sync

Readline-sync is a synchronous readline for interactively running to have a conversation with the user via a console(TTY). It's simpler and only supports synchronous operations, unlike 'prompts' which is designed around promises and async/await.

README

❯ Prompts

Lightweight, beautiful and user-friendly interactive prompts
_{>_ Easy to use CLI prompts to enquire users for information▌}

• Simple: prompts has no big dependencies nor is it broken into a dozen tiny modules that only work well together.
• User friendly: prompt uses layout and colors to create beautiful cli interfaces.
• Promised: uses promises and async/await. No callback hell.
• Flexible: all prompts are independent and can be used on their own.
• Testable: provides a way to submit answers programmatically.
• Unified: consistent experience across all prompts.

❯ Install

$ npm install --save prompts

This package supports Node 6 and above

❯ Usage

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.

❯ Examples

Single Prompt

Prompt with a single prompt object. Returns object with the response.

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.

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.

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
Returns: Object

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, response) where prompt is the current prompt object.

Return true to quit the prompt chain and return all collected responses so far, otherwise continue to iterate prompt objects.

Example:

let questions = [{ ... }];
let onSubmit = (prompt, response) => console.log(`Thanks I got ${response} from ${prompt.name}`);
let response = await prompts(questions, { onSubmit });

options.onCancel

Type: Function
Default: () => {}

Callback that's invoked when the user cancels/exits the prompt. Its signature is (prompt) where prompt is the current prompt object.

Return true to continue and prevent the prompt loop from aborting. On cancel responses collected so far are returned.

Example:

let questions = [{ ... }];
let onCancel = prompt => {
  console.log('Never stop prompting!');
  return true;
}
let response = await prompts(questions, { onCancel });

inject(values)

Type: Function

Programmatically inject responses. This enables you to prepare the responses ahead of time. If any injected values are found the prompt is immediately resolved with the injected value. This feature is intended for testing only.

values

Type: Object

Object with key/values to inject. Resolved values are deleted from the internel inject object.

Example:

const prompts = require('prompts');

prompts.inject({ q1: 'a1', q2: 'q2' });
let response = await prompts({
  type: 'text',
  name: 'q1',
  message: 'Question 1'
});

// => { q1: 'a1' }

When q1 resolves it's wiped. q2 doesn't resolve and is left untouched.

❯ Prompt Objects

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,
  onState: Function
}

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 suported 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.

Example:

{
    type: 'number',
    name: 'price',
    message: 'Enter price',
    format: val => Intl.NumberFormat(undefined, { style: 'currency', currency: 'USD' }).format(val);
}

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 have two properties value and aborted. E.g { value: 'This is ', aborted: false }

❯ Types

text(message, [initial], [style])

Text prompt for free text input.

Example

{
  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

{
  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

{
  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

{
  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

{
  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.

{
  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
seperator	string	','	String seperator. 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

{
  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

{
    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

{
    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

{
    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:

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.

❯ License

MIT © Terkel Gjervig