1 | <p align="center">
|
2 | <img src="https://github.com/terkelg/prompts/raw/master/prompts.png" alt="Prompts" width="500" />
|
3 | </p>
|
4 |
|
5 | <h1 align="center">❯ Prompts</h1>
|
6 |
|
7 | <p align="center">
|
8 | <a href="https://npmjs.org/package/prompts">
|
9 | <img src="https://img.shields.io/npm/v/prompts.svg" alt="version" />
|
10 | </a>
|
11 | <a href="https://travis-ci.org/terkelg/prompts">
|
12 | <img src="https://img.shields.io/travis/terkelg/prompts.svg" alt="travis" />
|
13 | </a>
|
14 | <a href="https://npmjs.org/package/prompts">
|
15 | <img src="https://img.shields.io/npm/dm/prompts.svg" alt="downloads" />
|
16 | </a>
|
17 | |
18 | <a href="https://packagephobia.now.sh/result?p=prompts">
|
19 | <img src="https://packagephobia.now.sh/badge?p=prompts" alt="install size" />
|
20 | </a>
|
21 | --->
|
22 | </p>
|
23 |
|
24 | <p align="center">
|
25 | <b>Lightweight, beautiful and user-friendly interactive prompts</b><br />
|
26 | <sub>>_ Easy to use CLI prompts to enquire users for information▌</sub>
|
27 | </p>
|
28 |
|
29 | <br />
|
30 |
|
31 | * **Simple**: prompts has [no big dependencies](http://npm.anvaka.com/#/view/2d/prompts) nor is it broken into a [dozen](http://npm.anvaka.com/#/view/2d/inquirer) tiny modules that only work well together.
|
32 | * **User friendly**: prompt uses layout and colors to create beautiful cli interfaces.
|
33 | * **Promised**: uses promises and `async`/`await`. No callback hell.
|
34 | * **Flexible**: all prompts are independent and can be used on their own.
|
35 | * **Testable**: provides a way to submit answers programmatically.
|
36 | * **Unified**: consistent experience across all [prompts](#-types).
|
37 |
|
38 |
|
39 | ![split](https://github.com/terkelg/prompts/raw/master/media/split.png)
|
40 |
|
41 |
|
42 | ## ❯ Install
|
43 |
|
44 | ```
|
45 | $ npm install --save prompts
|
46 | ```
|
47 |
|
48 | > This package supports Node 6 and above
|
49 |
|
50 | ![split](https://github.com/terkelg/prompts/raw/master/media/split.png)
|
51 |
|
52 | ## ❯ Usage
|
53 |
|
54 | <img src="https://github.com/terkelg/prompts/raw/master/media/example.gif" alt="example prompt" width="499" height="103" />
|
55 |
|
56 | ```js
|
57 | const prompts = require('prompts');
|
58 |
|
59 | (async () => {
|
60 | const response = await prompts({
|
61 | type: 'number',
|
62 | name: 'value',
|
63 | message: 'How old are you?',
|
64 | validate: value => value < 18 ? `Nightclub is 18+ only` : true
|
65 | });
|
66 |
|
67 | console.log(response); // => { value: 24 }
|
68 | })();
|
69 | ```
|
70 |
|
71 | > See [`example.js`](https://github.com/terkelg/prompts/blob/master/example.js) for more options.
|
72 |
|
73 |
|
74 | ![split](https://github.com/terkelg/prompts/raw/master/media/split.png)
|
75 |
|
76 |
|
77 | ## ❯ Examples
|
78 |
|
79 | ### Single Prompt
|
80 |
|
81 | Prompt with a single prompt object. Returns an object with the response.
|
82 |
|
83 | ```js
|
84 | const prompts = require('prompts');
|
85 |
|
86 | (async () => {
|
87 | const response = await prompts({
|
88 | type: 'text',
|
89 | name: 'meaning',
|
90 | message: 'What is the meaning of life?'
|
91 | });
|
92 |
|
93 | console.log(response.meaning);
|
94 | })();
|
95 | ```
|
96 |
|
97 | ### Prompt Chain
|
98 |
|
99 | Prompt with a list of prompt objects. Returns an object with the responses.
|
100 | Make sure to give each prompt a unique `name` property to prevent overwriting values.
|
101 |
|
102 | ```js
|
103 | const prompts = require('prompts');
|
104 |
|
105 | const questions = [
|
106 | {
|
107 | type: 'text',
|
108 | name: 'username',
|
109 | message: 'What is your GitHub username?'
|
110 | },
|
111 | {
|
112 | type: 'number',
|
113 | name: 'age',
|
114 | message: 'How old are you?'
|
115 | },
|
116 | {
|
117 | type: 'text',
|
118 | name: 'about',
|
119 | message: 'Tell something about yourself',
|
120 | initial: 'Why should I?'
|
121 | }
|
122 | ];
|
123 |
|
124 | (async () => {
|
125 | const response = await prompts(questions);
|
126 |
|
127 | // => response => { username, age, about }
|
128 | })();
|
129 | ```
|
130 |
|
131 | ### Dynamic Prompts
|
132 |
|
133 | Prompt properties can be functions too.
|
134 | Prompt Objects with `type` set to `falsy` values are skipped.
|
135 |
|
136 | ```js
|
137 | const prompts = require('prompts');
|
138 |
|
139 | const questions = [
|
140 | {
|
141 | type: 'text',
|
142 | name: 'dish',
|
143 | message: 'Do you like pizza?'
|
144 | },
|
145 | {
|
146 | type: prev => prev == 'pizza' ? 'text' : null,
|
147 | name: 'topping',
|
148 | message: 'Name a topping'
|
149 | }
|
150 | ];
|
151 |
|
152 | (async () => {
|
153 | const response = await prompts(questions);
|
154 | })();
|
155 | ```
|
156 |
|
157 |
|
158 | ![split](https://github.com/terkelg/prompts/raw/master/media/split.png)
|
159 |
|
160 |
|
161 | ## ❯ API
|
162 |
|
163 | ### prompts(prompts, options)
|
164 |
|
165 | Type: `Function`<br>
|
166 | Returns: `Object`
|
167 |
|
168 | Prompter function which takes your [prompt objects](#-prompt-objects) and returns an object with responses.
|
169 |
|
170 |
|
171 | #### prompts
|
172 |
|
173 | Type: `Array|Object`<br>
|
174 |
|
175 | Array of [prompt objects](#-prompt-objects).
|
176 | These are the questions the user will be prompted. You can see the list of supported [prompt types here](#-types).
|
177 |
|
178 | Prompts can be submitted (<kbd>return</kbd>, <kbd>enter</kbd>) or canceled (<kbd>esc</kbd>, <kbd>abort</kbd>, <kbd>ctrl</kbd>+<kbd>c</kbd>, <kbd>ctrl</kbd>+<kbd>d</kbd>). No property is being defined on the returned response object when a prompt is canceled.
|
179 |
|
180 | #### options.onSubmit
|
181 |
|
182 | Type: `Function`<br>
|
183 | Default: `() => {}`
|
184 |
|
185 | Callback that's invoked after each prompt submission.
|
186 | 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.
|
187 |
|
188 | Return `true` to quit the prompt chain and return all collected responses so far, otherwise continue to iterate prompt objects.
|
189 |
|
190 | **Example:**
|
191 | ```js
|
192 | (async () => {
|
193 | const questions = [{ ... }];
|
194 | const onSubmit = (prompt, answer) => console.log(`Thanks I got ${answer} from ${prompt.name}`);
|
195 | const response = await prompts(questions, { onSubmit });
|
196 | })();
|
197 | ```
|
198 |
|
199 | #### options.onCancel
|
200 |
|
201 | Type: `Function`<br>
|
202 | Default: `() => {}`
|
203 |
|
204 | Callback that's invoked when the user cancels/exits the prompt.
|
205 | Its signature is `(prompt, answers)` where `prompt` is the current prompt object and `answers` the user answers so far. Async functions are supported.
|
206 |
|
207 | Return `true` to continue and prevent the prompt loop from aborting.
|
208 | On cancel responses collected so far are returned.
|
209 |
|
210 | **Example:**
|
211 | ```js
|
212 | (async () => {
|
213 | const questions = [{ ... }];
|
214 | const onCancel = prompt => {
|
215 | console.log('Never stop prompting!');
|
216 | return true;
|
217 | }
|
218 | const response = await prompts(questions, { onCancel });
|
219 | })();
|
220 | ```
|
221 |
|
222 | ### override
|
223 |
|
224 | Type: `Function`
|
225 |
|
226 | Preanswer questions by passing an object with answers to `prompts.override`.
|
227 | Powerful when combined with arguments of process.
|
228 |
|
229 | **Example**
|
230 | ```js
|
231 | const prompts = require('prompts');
|
232 | prompts.override(require('yargs').argv);
|
233 |
|
234 | (async () => {
|
235 | const response = await prompts([
|
236 | {
|
237 | type: 'text',
|
238 | name: 'twitter',
|
239 | message: `What's your twitter handle?`
|
240 | },
|
241 | {
|
242 | type: 'multiselect',
|
243 | name: 'color',
|
244 | message: 'Pick colors',
|
245 | choices: [
|
246 | { title: 'Red', value: '#ff0000' },
|
247 | { title: 'Green', value: '#00ff00' },
|
248 | { title: 'Blue', value: '#0000ff' }
|
249 | ],
|
250 | }
|
251 | ]);
|
252 |
|
253 | console.log(response);
|
254 | })();
|
255 | ```
|
256 |
|
257 | ### inject(values)
|
258 |
|
259 | Type: `Function`<br>
|
260 |
|
261 | Programmatically inject responses. This enables you to prepare the responses ahead of time.
|
262 | If any injected value is found the prompt is immediately resolved with the injected value.
|
263 | This feature is intended for testing only.
|
264 |
|
265 | #### values
|
266 |
|
267 | Type: `Array`
|
268 |
|
269 | Array with values to inject. Resolved values are removed from the internal inject array.
|
270 | Each value can be an array of values in order to provide answers for a question asked multiple times.
|
271 | If a value is an instance of `Error` it will simulate the user cancelling/exiting the prompt.
|
272 |
|
273 | **Example:**
|
274 | ```js
|
275 | const prompts = require('prompts');
|
276 |
|
277 | prompts.inject([ '@terkelg', ['#ff0000', '#0000ff'] ]);
|
278 |
|
279 | (async () => {
|
280 | const response = await prompts([
|
281 | {
|
282 | type: 'text',
|
283 | name: 'twitter',
|
284 | message: `What's your twitter handle?`
|
285 | },
|
286 | {
|
287 | type: 'multiselect',
|
288 | name: 'color',
|
289 | message: 'Pick colors',
|
290 | choices: [
|
291 | { title: 'Red', value: '#ff0000' },
|
292 | { title: 'Green', value: '#00ff00' },
|
293 | { title: 'Blue', value: '#0000ff' }
|
294 | ],
|
295 | }
|
296 | ]);
|
297 |
|
298 | // => { twitter: 'terkelg', color: [ '#ff0000', '#0000ff' ] }
|
299 | })();
|
300 | ```
|
301 |
|
302 | ![split](https://github.com/terkelg/prompts/raw/master/media/split.png)
|
303 |
|
304 |
|
305 | ## ❯ Prompt Objects
|
306 |
|
307 | Prompts Objects are JavaScript objects that define the "questions" and the [type of prompt](#-types).
|
308 | Almost all prompt objects have the following properties:
|
309 |
|
310 | ```js
|
311 | {
|
312 | type: String | Function,
|
313 | name: String | Function,
|
314 | message: String | Function,
|
315 | initial: String | Function | Async Function
|
316 | format: Function | Async Function,
|
317 | onRender: Function
|
318 | onState: Function
|
319 | stdin: Readable
|
320 | stdout: Writeable
|
321 | }
|
322 | ```
|
323 |
|
324 | Each property be of type `function` and will be invoked right before prompting the user.
|
325 |
|
326 | The function signature is `(prev, values, prompt)`, where `prev` is the value from the previous prompt,
|
327 | `values` is the response object with all values collected so far and `prompt` is the previous prompt object.
|
328 |
|
329 | **Function example:**
|
330 | ```js
|
331 | {
|
332 | type: prev => prev > 3 ? 'confirm' : null,
|
333 | name: 'confirm',
|
334 | message: (prev, values) => `Please confirm that you eat ${values.dish} times ${prev} a day?`
|
335 | }
|
336 | ```
|
337 |
|
338 | The above prompt will be skipped if the value of the previous prompt is less than 3.
|
339 |
|
340 | ### type
|
341 |
|
342 | Type: `String|Function`
|
343 |
|
344 | Defines the type of prompt to display. See the list of [prompt types](#-types) for valid values.
|
345 |
|
346 | If `type` is a falsy value the prompter will skip that question.
|
347 | ```js
|
348 | {
|
349 | type: null,
|
350 | name: 'forgetme',
|
351 | message: `I'll never be shown anyway`,
|
352 | }
|
353 | ```
|
354 |
|
355 | ### name
|
356 |
|
357 | Type: `String|Function`
|
358 |
|
359 | The response will be saved under this key/property in the returned response object.
|
360 | In case you have multiple prompts with the same name only the latest response will be stored.
|
361 |
|
362 | > Make sure to give prompts unique names if you don't want to overwrite previous values.
|
363 |
|
364 | ### message
|
365 |
|
366 | Type: `String|Function`
|
367 |
|
368 | The message to be displayed to the user.
|
369 |
|
370 | ### initial
|
371 |
|
372 | Type: `String|Function`
|
373 |
|
374 | Optional default prompt value. Async functions are supported too.
|
375 |
|
376 | ### format
|
377 |
|
378 | Type: `Function`
|
379 |
|
380 | Receive the user input and return the formatted value to be used inside the program.
|
381 | The value returned will be added to the response object.
|
382 |
|
383 | The function signature is `(val, values)`, where `val` is the value from the current prompt and
|
384 | `values` is the current response object in case you need to format based on previous responses.
|
385 |
|
386 | **Example:**
|
387 | ```js
|
388 | {
|
389 | type: 'number',
|
390 | name: 'price',
|
391 | message: 'Enter price',
|
392 | format: val => Intl.NumberFormat(undefined, { style: 'currency', currency: 'USD' }).format(val);
|
393 | }
|
394 | ```
|
395 |
|
396 | ### onRender
|
397 |
|
398 | Type: `Function`
|
399 |
|
400 | Callback for when the prompt is rendered.
|
401 | The function receives [kleur](https://github.com/lukeed/kleur) as its first argument and `this` refers to the current prompt.
|
402 |
|
403 | **Example:**
|
404 | ```js
|
405 | {
|
406 | type: 'number',
|
407 | message: 'This message will be overridden',
|
408 | onRender(kleur) {
|
409 | this.msg = kleur.cyan('Enter a number');
|
410 | }
|
411 | }
|
412 | ```
|
413 |
|
414 | ### onState
|
415 |
|
416 | Type: `Function`
|
417 |
|
418 | Callback for when the state of the current prompt changes.
|
419 | The function signature is `(state)` where `state` is an object with a snapshot of the current state.
|
420 | The state object has two properties `value` and `aborted`. E.g `{ value: 'This is ', aborted: false }`
|
421 |
|
422 | ### stdin and stdout
|
423 |
|
424 | Type: `Stream`
|
425 |
|
426 | By default, prompts uses `process.stdin` for receiving input and `process.stdout` for writing output.
|
427 | If you need to use different streams, for instance `process.stderr`, you can set these with the `stdin` and `stdout` properties.
|
428 |
|
429 |
|
430 | ![split](https://github.com/terkelg/prompts/raw/master/media/split.png)
|
431 |
|
432 |
|
433 | ## ❯ Types
|
434 |
|
435 | * [text](#textmessage-initial-style)
|
436 | * [password](#passwordmessage-initial)
|
437 | * [invisible](#invisiblemessage-initial)
|
438 | * [number](#numbermessage-initial-max-min-style)
|
439 | * [confirm](#confirmmessage-initial)
|
440 | * [list](#listmessage-initial)
|
441 | * [toggle](#togglemessage-initial-active-inactive)
|
442 | * [select](#selectmessage-choices-initial-hint-warn)
|
443 | * [multiselect](#multiselectmessage-choices-initial-max-hint-warn)
|
444 | * [autocompleteMultiselect](#multiselectmessage-choices-initial-max-hint-warn)
|
445 | * [autocomplete](#autocompletemessage-choices-initial-suggest-limit-style)
|
446 | * [date](#datemessage-initial-warn)
|
447 |
|
448 | ***
|
449 |
|
450 | ### text(message, [initial], [style])
|
451 | > Text prompt for free text input.
|
452 |
|
453 | Hit <kbd>tab</kbd> to autocomplete to `initial` value when provided.
|
454 |
|
455 | #### Example
|
456 | <img src="https://github.com/terkelg/prompts/raw/master/media/text.gif" alt="text prompt" width="499" height="103" />
|
457 |
|
458 | ```js
|
459 | {
|
460 | type: 'text',
|
461 | name: 'value',
|
462 | message: `What's your twitter handle?`
|
463 | }
|
464 | ```
|
465 |
|
466 | #### Options
|
467 | | Param | Type | Description |
|
468 | | ----- | :--: | ----------- |
|
469 | | message | `string` | Prompt message to display |
|
470 | | initial | `string` | Default string value |
|
471 | | style | `string` | Render style (`default`, `password`, `invisible`, `emoji`). Defaults to `default` |
|
472 | | format | `function` | Receive user input. The returned value will be added to the response object |
|
473 | | 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 |
|
474 | | onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
|
475 | | onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |
|
476 |
|
477 | **↑ back to:** [Prompt types](#-types)
|
478 |
|
479 | ***
|
480 |
|
481 | ### password(message, [initial])
|
482 | > Password prompt with masked input.
|
483 |
|
484 | This prompt is a similar to a prompt of type `'text'` with `style` set to `'password'`.
|
485 |
|
486 | #### Example
|
487 | <img src="https://github.com/terkelg/prompts/raw/master/media/password.gif" alt="password prompt" width="499" height="103" />
|
488 |
|
489 | ```js
|
490 | {
|
491 | type: 'password',
|
492 | name: 'value',
|
493 | message: 'Tell me a secret'
|
494 | }
|
495 | ```
|
496 |
|
497 | #### Options
|
498 | | Param | Type | Description |
|
499 | | ----- | :--: | ----------- |
|
500 | | message | `string` | Prompt message to display |
|
501 | | initial | `string` | Default string value |
|
502 | | format | `function` | Receive user input. The returned value will be added to the response object |
|
503 | | 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 |
|
504 | | onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
|
505 | | onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |
|
506 |
|
507 | **↑ back to:** [Prompt types](#-types)
|
508 |
|
509 | ***
|
510 |
|
511 | ### invisible(message, [initial])
|
512 | > Prompts user for invisible text input.
|
513 |
|
514 | This prompt is working like `sudo` where the input is invisible.
|
515 | This prompt is a similar to a prompt of type `'text'` with style set to `'invisible'`.
|
516 |
|
517 | #### Example
|
518 | <img src="https://github.com/terkelg/prompts/raw/master/media/invisible.gif" alt="invisible prompt" width="499" height="103" />
|
519 |
|
520 | ```js
|
521 | {
|
522 | type: 'invisible',
|
523 | name: 'value',
|
524 | message: 'Enter password'
|
525 | }
|
526 | ```
|
527 |
|
528 | #### Options
|
529 | | Param | Type | Description |
|
530 | | ----- | :--: | ----------- |
|
531 | | message | `string` | Prompt message to display |
|
532 | | initial | `string` | Default string value |
|
533 | | format | `function` | Receive user input. The returned value will be added to the response object |
|
534 | | 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 |
|
535 | | onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
|
536 | | onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |
|
537 |
|
538 | **↑ back to:** [Prompt types](#-types)
|
539 |
|
540 | ***
|
541 |
|
542 | ### number(message, initial, [max], [min], [style])
|
543 | > Prompts user for number input.
|
544 |
|
545 | You can type in numbers and use <kbd>up</kbd>/<kbd>down</kbd> to increase/decrease the value. Only numbers are allowed as input. Hit <kbd>tab</kbd> to autocomplete to `initial` value when provided.
|
546 |
|
547 | #### Example
|
548 | <img src="https://github.com/terkelg/prompts/raw/master/media/number.gif" alt="number prompt" width="499" height="103" />
|
549 |
|
550 | ```js
|
551 | {
|
552 | type: 'number',
|
553 | name: 'value',
|
554 | message: 'How old are you?',
|
555 | initial: 0,
|
556 | style: 'default',
|
557 | min: 2,
|
558 | max: 10
|
559 | }
|
560 | ```
|
561 |
|
562 | #### Options
|
563 | | Param | Type | Description |
|
564 | | ----- | :--: | ----------- |
|
565 | | message | `string` | Prompt message to display |
|
566 | | initial | `number` | Default number value |
|
567 | | format | `function` | Receive user input. The returned value will be added to the response object |
|
568 | | 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 |
|
569 | | max | `number` | Max value. Defaults to `Infinity` |
|
570 | | min | `number` | Min value. Defaults to `-infinity` |
|
571 | | float | `boolean` | Allow floating point inputs. Defaults to `false` |
|
572 | | round | `number` | Round `float` values to x decimals. Defaults to `2` |
|
573 | | increment | `number` | Increment step when using <kbd>arrow</kbd> keys. Defaults to `1` |
|
574 | | style | `string` | Render style (`default`, `password`, `invisible`, `emoji`). Defaults to `default` |
|
575 | | onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
|
576 | | onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |
|
577 |
|
578 | **↑ back to:** [Prompt types](#-types)
|
579 |
|
580 | ***
|
581 |
|
582 | ### confirm(message, [initial])
|
583 | > Classic yes/no prompt.
|
584 |
|
585 | Hit <kbd>y</kbd> or <kbd>n</kbd> to confirm/reject.
|
586 |
|
587 | #### Example
|
588 | <img src="https://github.com/terkelg/prompts/raw/master/media/confirm.gif" alt="confirm prompt" width="499" height="103" />
|
589 |
|
590 | ```js
|
591 | {
|
592 | type: 'confirm',
|
593 | name: 'value',
|
594 | message: 'Can you confirm?',
|
595 | initial: true
|
596 | }
|
597 | ```
|
598 |
|
599 |
|
600 | #### Options
|
601 | | Param | Type | Description |
|
602 | | ----- | :--: | ----------- |
|
603 | | message | `string` | Prompt message to display |
|
604 | | initial | `boolean` | Default value. Default is `false` |
|
605 | | format | `function` | Receive user input. The returned value will be added to the response object |
|
606 | | onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
|
607 | | onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |
|
608 |
|
609 | **↑ back to:** [Prompt types](#-types)
|
610 |
|
611 | ***
|
612 |
|
613 | ### list(message, [initial])
|
614 | > List prompt that return an array.
|
615 |
|
616 | Similar to the `text` prompt, but the output is an `Array` containing the
|
617 | string separated by `separator`.
|
618 |
|
619 | ```js
|
620 | {
|
621 | type: 'list',
|
622 | name: 'value',
|
623 | message: 'Enter keywords',
|
624 | initial: '',
|
625 | separator: ','
|
626 | }
|
627 | ```
|
628 |
|
629 | <img src="https://github.com/terkelg/prompts/raw/master/media/list.gif" alt="list prompt" width="499" height="103" />
|
630 |
|
631 |
|
632 | | Param | Type | Description |
|
633 | | ----- | :--: | ----------- |
|
634 | | message | `string` | Prompt message to display |
|
635 | | initial | `boolean` | Default value |
|
636 | | format | `function` | Receive user input. The returned value will be added to the response object |
|
637 | | separator | `string` | String separator. Will trim all white-spaces from start and end of string. Defaults to `','` |
|
638 | | onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
|
639 | | onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |
|
640 |
|
641 | **↑ back to:** [Prompt types](#-types)
|
642 |
|
643 | ***
|
644 |
|
645 | ### toggle(message, [initial], [active], [inactive])
|
646 | > Interactive toggle/switch prompt.
|
647 |
|
648 | Use tab or <kbd>arrow keys</kbd>/<kbd>tab</kbd>/<kbd>space</kbd> to switch between options.
|
649 |
|
650 | #### Example
|
651 | <img src="https://github.com/terkelg/prompts/raw/master/media/toggle.gif" alt="toggle prompt" width="499" height="103" />
|
652 |
|
653 | ```js
|
654 | {
|
655 | type: 'toggle',
|
656 | name: 'value',
|
657 | message: 'Can you confirm?',
|
658 | initial: true,
|
659 | active: 'yes',
|
660 | inactive: 'no'
|
661 | }
|
662 | ```
|
663 |
|
664 | #### Options
|
665 | | Param | Type | Description |
|
666 | | ----- | :--: | ----------- |
|
667 | | message | `string` | Prompt message to display |
|
668 | | initial | `boolean` | Default value. Defaults to `false` |
|
669 | | format | `function` | Receive user input. The returned value will be added to the response object |
|
670 | | active | `string` | Text for `active` state. Defaults to `'on'` |
|
671 | | inactive | `string` | Text for `inactive` state. Defaults to `'off'` |
|
672 | | onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
|
673 | | onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |
|
674 |
|
675 | **↑ back to:** [Prompt types](#-types)
|
676 |
|
677 | ***
|
678 |
|
679 | ### select(message, choices, [initial], [hint], [warn])
|
680 | > Interactive select prompt.
|
681 |
|
682 | Use <kbd>up</kbd>/<kbd>down</kbd> to navigate. Use <kbd>tab</kbd> to cycle the list.
|
683 |
|
684 | #### Example
|
685 | <img src="https://github.com/terkelg/prompts/raw/master/media/select.gif" alt="select prompt" width="499" height="130" />
|
686 |
|
687 | ```js
|
688 | {
|
689 | type: 'select',
|
690 | name: 'value',
|
691 | message: 'Pick a color',
|
692 | choices: [
|
693 | { title: 'Red', description: 'This option has a description', value: '#ff0000' },
|
694 | { title: 'Green', value: '#00ff00', disabled: true },
|
695 | { title: 'Blue', value: '#0000ff' }
|
696 | ],
|
697 | initial: 1
|
698 | }
|
699 | ```
|
700 |
|
701 | #### Options
|
702 | | Param | Type | Description |
|
703 | | ----- | :--: | ----------- |
|
704 | | message | `string` | Prompt message to display |
|
705 | | initial | `number` | Index of default value |
|
706 | | format | `function` | Receive user input. The returned value will be added to the response object |
|
707 | | hint | `string` | Hint to display to the user |
|
708 | | warn | `string` | Message to display when selecting a disabled option |
|
709 | | 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. |
|
710 | | onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
|
711 | | onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |
|
712 |
|
713 | **↑ back to:** [Prompt types](#-types)
|
714 |
|
715 | ***
|
716 |
|
717 | ### multiselect(message, choices, [initial], [max], [hint], [warn])
|
718 | ### autocompleteMultiselect(same)
|
719 | > Interactive multi-select prompt.
|
720 | > Autocomplete is a searchable multiselect prompt with the same options. Useful for long lists.
|
721 |
|
722 | Use <kbd>space</kbd> to toggle select/unselect and <kbd>up</kbd>/<kbd>down</kbd> to navigate. Use <kbd>tab</kbd> to cycle the list. You can also use <kbd>right</kbd> to select and <kbd>left</kbd> to deselect.
|
723 | By default this prompt returns an `array` containing the **values** of the selected items - not their display title.
|
724 |
|
725 | #### Example
|
726 | <img src="https://github.com/terkelg/prompts/raw/master/media/multiselect.gif" alt="multiselect prompt" width="499" height="130" />
|
727 |
|
728 | ```js
|
729 | {
|
730 | type: 'multiselect',
|
731 | name: 'value',
|
732 | message: 'Pick colors',
|
733 | choices: [
|
734 | { title: 'Red', value: '#ff0000' },
|
735 | { title: 'Green', value: '#00ff00', disabled: true },
|
736 | { title: 'Blue', value: '#0000ff', selected: true }
|
737 | ],
|
738 | max: 2,
|
739 | hint: '- Space to select. Return to submit'
|
740 | }
|
741 | ```
|
742 |
|
743 | #### Options
|
744 | | Param | Type | Description |
|
745 | | ----- | :--: | ----------- |
|
746 | | message | `string` | Prompt message to display |
|
747 | | format | `function` | Receive user input. The returned value will be added to the response object |
|
748 | | instructions | `string` or `boolean` | Prompt instructions to display |
|
749 | | 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. |
|
750 | | optionsPerPage | `number` | Number of options displayed per page (default: 10) |
|
751 | | min | `number` | Min select - will display error |
|
752 | | max | `number` | Max select |
|
753 | | hint | `string` | Hint to display to the user |
|
754 | | warn | `string` | Message to display when selecting a disabled option |
|
755 | | onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
|
756 | | onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |
|
757 |
|
758 | This is one of the few prompts that don't take a initial value.
|
759 | If you want to predefine selected values, give the choice object an `selected` property of `true`.
|
760 |
|
761 | **↑ back to:** [Prompt types](#-types)
|
762 |
|
763 | ***
|
764 |
|
765 | ### autocomplete(message, choices, [initial], [suggest], [limit], [style])
|
766 | > Interactive auto complete prompt.
|
767 |
|
768 | The prompt will list options based on user input. Type to filter the list.
|
769 | Use <kbd>⇧</kbd>/<kbd>⇩</kbd> to navigate. Use <kbd>tab</kbd> to cycle the result. Use <kbd>Page Up</kbd>/<kbd>Page Down</kbd> (on Mac: <kbd>fn</kbd> + <kbd>⇧</kbd> / <kbd>⇩</kbd>) to change page. Hit <kbd>enter</kbd> to select the highlighted item below the prompt.
|
770 |
|
771 | The default suggests function is sorting based on the `title` property of the choices.
|
772 | You can overwrite how choices are being filtered by passing your own suggest function.
|
773 |
|
774 | #### Example
|
775 | <img src="https://github.com/terkelg/prompts/raw/master/media/autocomplete.gif" alt="auto complete prompt" width="499" height="163" />
|
776 |
|
777 | ```js
|
778 | {
|
779 | type: 'autocomplete',
|
780 | name: 'value',
|
781 | message: 'Pick your favorite actor',
|
782 | choices: [
|
783 | { title: 'Cage' },
|
784 | { title: 'Clooney', value: 'silver-fox' },
|
785 | { title: 'Gyllenhaal' },
|
786 | { title: 'Gibson' },
|
787 | { title: 'Grant' }
|
788 | ]
|
789 | }
|
790 | ```
|
791 |
|
792 | #### Options
|
793 | | Param | Type | Description |
|
794 | | ----- | :--: | ----------- |
|
795 | | message | `string` | Prompt message to display |
|
796 | | format | `function` | Receive user input. The returned value will be added to the response object |
|
797 | | choices | `Array` | Array of auto-complete choices objects `[{ title, value }, ...]` |
|
798 | | suggest | `function` | Filter function. Defaults to sort by `title` property. `suggest` should always return a promise. Filters using `title` by default |
|
799 | | limit | `number` | Max number of results to show. Defaults to `10` |
|
800 | | style | `string` | Render style (`default`, `password`, `invisible`, `emoji`). Defaults to `'default'` |
|
801 | | initial | `string \| number` | Default initial value |
|
802 | | clearFirst | `boolean` | The first ESCAPE keypress will clear the input |
|
803 | | fallback | `string` | Fallback message when no match is found. Defaults to `initial` value if provided |
|
804 | | onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
|
805 | | onState | `function` | On state change callback. Function signature is an `object` with three properties: `value`, `aborted` and `exited` |
|
806 |
|
807 | Example on what a `suggest` function might look like:
|
808 | ```js
|
809 | const suggestByTitle = (input, choices) =>
|
810 | Promise.resolve(choices.filter(i => i.title.slice(0, input.length) === input))
|
811 | ```
|
812 |
|
813 | **↑ back to:** [Prompt types](#-types)
|
814 |
|
815 | ***
|
816 |
|
817 | ### date(message, [initial], [warn])
|
818 | > Interactive date prompt.
|
819 |
|
820 | Use <kbd>left</kbd>/<kbd>right</kbd>/<kbd>tab</kbd> to navigate. Use <kbd>up</kbd>/<kbd>down</kbd> to change date.
|
821 |
|
822 | #### Example
|
823 | <img src="https://github.com/terkelg/prompts/raw/master/media/date.gif" alt="date prompt" width="499" height="103" />
|
824 |
|
825 | ```js
|
826 | {
|
827 | type: 'date',
|
828 | name: 'value',
|
829 | message: 'Pick a date',
|
830 | initial: new Date(1997, 09, 12),
|
831 | validate: date => date > Date.now() ? 'Not in the future' : true
|
832 | }
|
833 | ```
|
834 |
|
835 | #### Options
|
836 | | Param | Type | Description |
|
837 | | ----- | :--: | ----------- |
|
838 | | message | `string` | Prompt message to display |
|
839 | | initial | `date` | Default date |
|
840 | | locales | `object` | Use to define custom locales. See below for an example. |
|
841 | | mask | `string` | The format mask of the date. See below for more information.<br />Default: `YYYY-MM-DD HH:mm:ss` |
|
842 | | 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 |
|
843 | | onRender | `function` | On render callback. Keyword `this` refers to the current prompt |
|
844 | | onState | `function` | On state change callback. Function signature is an `object` with two properties: `value` and `aborted` |
|
845 |
|
846 | Default locales:
|
847 |
|
848 | ```javascript
|
849 | {
|
850 | months: [
|
851 | 'January', 'February', 'March', 'April',
|
852 | 'May', 'June', 'July', 'August',
|
853 | 'September', 'October', 'November', 'December'
|
854 | ],
|
855 | monthsShort: [
|
856 | 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
|
857 | 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
|
858 | ],
|
859 | weekdays: [
|
860 | 'Sunday', 'Monday', 'Tuesday', 'Wednesday',
|
861 | 'Thursday', 'Friday', 'Saturday'
|
862 | ],
|
863 | weekdaysShort: [
|
864 | 'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'
|
865 | ]
|
866 | }
|
867 | ```
|
868 | >**Formatting**: See full list of formatting options in the [wiki](https://github.com/terkelg/prompts/wiki/Date-Time-Formatting)
|
869 |
|
870 | ![split](https://github.com/terkelg/prompts/raw/master/media/split.png)
|
871 |
|
872 | **↑ back to:** [Prompt types](#-types)
|
873 |
|
874 | ***
|
875 |
|
876 | ## ❯ Credit
|
877 | Many of the prompts are based on the work of [derhuerst](https://github.com/derhuerst).
|
878 |
|
879 |
|
880 | ## ❯ License
|
881 |
|
882 | MIT © [Terkel Gjervig](https://terkel.com)
|