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.