0
# Prompts
1
2
Prompts is a lightweight, beautiful and user-friendly interactive CLI prompts library with promise-based API and async/await support. It provides a comprehensive set of prompt types for gathering user input in command-line applications, with beautiful styling, flexible validation, and consistent experience across all prompt types.
3
4
## Package Information
5
6
- **Package Name**: prompts
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install prompts`
10
- **Node Support**: >= 6
11
12
## Core Imports
13
14
```javascript
15
const prompts = require('prompts');
16
```
17
18
For ES modules:
19
20
```javascript
21
import prompts from 'prompts';
22
```
23
24
Import specific functions:
25
26
```javascript
27
const { prompt, inject, override } = require('prompts');
28
```
29
30
## Basic Usage
31
32
```javascript
33
const prompts = require('prompts');
34
35
// Single prompt
36
const response = await prompts({
37
type: 'text',
38
name: 'username',
39
message: 'What is your GitHub username?'
40
});
41
console.log(response.username);
42
43
// Multiple prompts
44
const response = await prompts([
45
{
46
type: 'text',
47
name: 'username',
48
message: 'What is your GitHub username?'
49
},
50
{
51
type: 'number',
52
name: 'age',
53
message: 'How old are you?'
54
},
55
{
56
type: 'confirm',
57
name: 'subscribe',
58
message: 'Would you like to subscribe to our newsletter?'
59
}
60
]);
61
62
console.log(response); // { username: 'alice', age: 25, subscribe: true }
63
```
64
65
## Architecture
66
67
Prompts is built around several key components:
68
69
- **Main Prompt Function**: Core prompting function that handles question flow, validation, and response collection
70
- **Prompt Types**: Eleven different prompt types for various input scenarios (text, number, select, etc.)
71
- **Element Classes**: Individual prompt implementation classes that handle rendering and user interaction
72
- **Testing Utilities**: Functions for programmatic response injection and pre-answering questions
73
- **Utility Modules**: Helper functions for styling, formatting, and terminal interaction
74
75
## Capabilities
76
77
### Core Prompting
78
79
Main prompting functionality for single or multiple questions with promise-based API, validation, and callback support.
80
81
```javascript { .api }
82
function prompts(
83
questions: Question | Question[],
84
options?: PromptOptions
85
): Promise<Answers>;
86
87
interface Question {
88
type: string | ((prev: any, values: Answers, prompt: Question) => string | null);
89
name: string | ((prev: any, values: Answers, prompt: Question) => string);
90
message: string | ((prev: any, values: Answers, prompt: Question) => string);
91
initial?: any | ((prev: any, values: Answers, prompt: Question) => any);
92
format?: (val: any, values: Answers) => any;
93
validate?: (val: any, values: Answers) => boolean | string;
94
onRender?: (kleur: any) => void;
95
onState?: (state: { value: any; aborted: boolean }) => void;
96
stdin?: NodeJS.ReadableStream;
97
stdout?: NodeJS.WritableStream;
98
}
99
100
interface PromptOptions {
101
onSubmit?: (prompt: Question, answer: any, answers: Answers) => boolean | Promise<boolean>;
102
onCancel?: (prompt: Question, answers: Answers) => boolean | Promise<boolean>;
103
}
104
105
type Answers = Record<string, any>;
106
```
107
108
[Core Prompting](./core-prompting.md)
109
110
### Text Input Prompts
111
112
Text-based input prompts including standard text, password (masked), and invisible input modes.
113
114
```javascript { .api }
115
// Text prompt
116
{
117
type: 'text',
118
name: 'value',
119
message: string,
120
initial?: string,
121
style?: 'default' | 'password' | 'invisible' | 'emoji',
122
validate?: (value: string) => boolean | string,
123
format?: (value: string) => any
124
}
125
126
// Password prompt (masked input)
127
{
128
type: 'password',
129
name: 'value',
130
message: string,
131
initial?: string
132
}
133
134
// Invisible prompt (like sudo)
135
{
136
type: 'invisible',
137
name: 'value',
138
message: string,
139
initial?: string
140
}
141
```
142
143
[Text Input Prompts](./text-prompts.md)
144
145
### Number and Date Prompts
146
147
Numeric and temporal input prompts with validation, increment/decrement controls, and locale support.
148
149
```javascript { .api }
150
// Number prompt
151
{
152
type: 'number',
153
name: 'value',
154
message: string,
155
initial?: number,
156
max?: number,
157
min?: number,
158
float?: boolean,
159
round?: number,
160
increment?: number,
161
style?: 'default' | 'password' | 'invisible' | 'emoji'
162
}
163
164
// Date prompt
165
{
166
type: 'date',
167
name: 'value',
168
message: string,
169
initial?: Date,
170
locales?: DateLocales,
171
mask?: string,
172
validate?: (date: Date) => boolean | string
173
}
174
```
175
176
[Number and Date Prompts](./number-date-prompts.md)
177
178
### Choice Selection Prompts
179
180
Interactive selection prompts for single choice, multiple choice, and searchable selection from predefined options.
181
182
```javascript { .api }
183
// Single selection
184
{
185
type: 'select',
186
name: 'value',
187
message: string,
188
choices: Choice[],
189
initial?: number,
190
hint?: string,
191
warn?: string
192
}
193
194
// Multiple selection
195
{
196
type: 'multiselect',
197
name: 'value',
198
message: string,
199
choices: Choice[],
200
max?: number,
201
min?: number,
202
hint?: string,
203
warn?: string,
204
instructions?: string | boolean,
205
optionsPerPage?: number
206
}
207
208
// Autocomplete selection
209
{
210
type: 'autocomplete',
211
name: 'value',
212
message: string,
213
choices: Choice[],
214
suggest?: (input: string, choices: Choice[]) => Promise<Choice[]>,
215
limit?: number,
216
style?: string,
217
initial?: string | number,
218
clearFirst?: boolean,
219
fallback?: string
220
}
221
222
interface Choice {
223
title: string;
224
value?: any;
225
description?: string;
226
disabled?: boolean;
227
selected?: boolean; // for multiselect only
228
}
229
```
230
231
[Choice Selection Prompts](./choice-prompts.md)
232
233
### Confirmation and Toggle Prompts
234
235
Binary choice prompts for yes/no confirmations and toggle switches with custom labels.
236
237
```javascript { .api }
238
// Confirmation prompt
239
{
240
type: 'confirm',
241
name: 'value',
242
message: string,
243
initial?: boolean
244
}
245
246
// Toggle prompt
247
{
248
type: 'toggle',
249
name: 'value',
250
message: string,
251
initial?: boolean,
252
active?: string,
253
inactive?: string
254
}
255
256
// List prompt
257
{
258
type: 'list',
259
name: 'value',
260
message: string,
261
initial?: string,
262
separator?: string
263
}
264
```
265
266
[Confirmation and Toggle Prompts](./confirmation-prompts.md)
267
268
### Testing Utilities
269
270
Functions for programmatic testing, response injection, and pre-answering questions during automated testing scenarios.
271
272
```javascript { .api }
273
function inject(answers: any[]): void;
274
function override(answers: Record<string, any>): void;
275
```
276
277
[Testing Utilities](./testing.md)
278
279
## Common Properties
280
281
All prompt types support these common properties:
282
283
- **type**: Prompt type identifier or function returning type
284
- **name**: Property name for the response object or function returning name
285
- **message**: Display message for the user or function returning message
286
- **initial**: Default/initial value or function returning initial value
287
- **format**: Custom formatter function for user input
288
- **validate**: Input validation function returning true or error message
289
- **onState**: State change callback with current state object
290
- **onRender**: Render callback with kleur styling library access
291
- **stdin**: Input stream (defaults to process.stdin)
292
- **stdout**: Output stream (defaults to process.stdout)
293
294
Dynamic properties can be functions with signature `(prev, values, prompt) => value` where:
295
- `prev`: Value from the previous prompt
296
- `values`: All collected responses so far
297
- `prompt`: Previous prompt object
298
299
## Error Handling
300
301
Prompts can be canceled by users with Esc, Ctrl+C, or Ctrl+D. When canceled, the promise resolves with partial answers collected so far. Use the `onCancel` callback to handle cancellation events.
302
303
The `validate` function should return `true` for valid input or an error message string for invalid input. If `false` is returned, a default error message is shown.