0
# Choice Selection Prompts
1

2
Interactive selection prompts for choosing from predefined options, including single selection, multiple selection, and searchable autocomplete selection. All choice prompts support disabled options, custom values, and descriptive text.
3

4
```javascript
5
const prompts = require('prompts');
6
```
7

8
## Capabilities
9

10
### Select Prompt
11

12
Single-choice selection prompt with keyboard navigation through a list of options. Users can navigate with arrow keys and select with Enter.
13

14
```javascript { .api }
15
{
16
  /** Prompt type identifier */
17
  type: 'select',
18
  /** Property name for response object */
19
  name: string,
20
  /** Display message for user */
21
  message: string,
22
  /** Array of choice objects or strings */
23
  choices: Choice[],
24
  /** Index of default selected choice */
25
  initial?: number,
26
  /** Hint text displayed to user */
27
  hint?: string,
28
  /** Warning message when selecting disabled option */
29
  warn?: string,
30
  /** Custom formatter for selected value */
31
  format?: (value: any, values: Answers) => any,
32
  /** Render callback with kleur styling */
33
  onRender?: (kleur: any) => void,
34
  /** State change callback */
35
  onState?: (state: { value: any; aborted: boolean }) => void,
36
  /** Input stream */
37
  stdin?: NodeJS.ReadableStream,
38
  /** Output stream */
39
  stdout?: NodeJS.WritableStream
40
}
41

42
interface Choice {
43
  /** Display title for the choice */
44
  title: string;
45
  /** Value to store when selected. Defaults to array index if not specified */
46
  value?: any;
47
  /** Optional description text shown below title */
48
  description?: string;
49
  /** Whether this choice is disabled and cannot be selected */
50
  disabled?: boolean;
51
}
52
```
53

54
**Usage Examples:**
55

56
```javascript
57
const prompts = require('prompts');
58

59
// Basic select prompt
60
const response = await prompts({
61
  type: 'select',
62
  name: 'color',
63
  message: 'Pick a color',
64
  choices: [
65
    { title: 'Red', value: '#ff0000' },
66
    { title: 'Green', value: '#00ff00' },
67
    { title: 'Blue', value: '#0000ff' }
68
  ],
69
  initial: 1
70
});
71

72
// Select with descriptions and disabled option
73
const response = await prompts({
74
  type: 'select',
75
  name: 'plan',
76
  message: 'Choose your plan',
77
  choices: [
78
    { 
79
      title: 'Free', 
80
      description: 'Basic features with usage limits',
81
      value: 'free' 
82
    },
83
    { 
84
      title: 'Pro', 
85
      description: 'Advanced features with higher limits',
86
      value: 'pro' 
87
    },
88
    { 
89
      title: 'Enterprise', 
90
      description: 'Full features with unlimited usage',
91
      value: 'enterprise',
92
      disabled: true
93
    }
94
  ],
95
  hint: '- Use arrow keys. Return to submit',
96
  warn: 'This option is not available in your region'
97
});
98
```
99

100
### Multiselect Prompt
101

102
Multiple-choice selection prompt allowing users to select multiple options from a list. Returns an array of selected values.
103

104
```javascript { .api }
105
{
106
  /** Prompt type identifier */
107
  type: 'multiselect',
108
  /** Property name for response object */
109
  name: string,
110
  /** Display message for user */
111
  message: string,
112
  /** Array of choice objects with optional pre-selection */
113
  choices: MultiselectChoice[],
114
  /** Maximum number of selections allowed */
115
  max?: number,
116
  /** Minimum number of selections required */
117
  min?: number,
118
  /** Hint text displayed to user */
119
  hint?: string,
120
  /** Warning message when selecting disabled option */
121
  warn?: string,
122
  /** Instructions text or boolean to show/hide default instructions */
123
  instructions?: string | boolean,
124
  /** Number of options to display per page. Defaults to 10 */
125
  optionsPerPage?: number,
126
  /** Custom formatter for selected values array */
127
  format?: (values: any[], allValues: Answers) => any,
128
  /** Render callback with kleur styling */
129
  onRender?: (kleur: any) => void,
130
  /** State change callback */
131
  onState?: (state: { value: any[]; aborted: boolean }) => void,
132
  /** Input stream */
133
  stdin?: NodeJS.ReadableStream,
134
  /** Output stream */
135
  stdout?: NodeJS.WritableStream
136
}
137

138
interface MultiselectChoice {
139
  /** Display title for the choice */
140
  title: string;
141
  /** Value to store when selected. Defaults to array index if not specified */
142
  value?: any;
143
  /** Optional description text shown below title */
144
  description?: string;
145
  /** Whether this choice is disabled and cannot be selected */
146
  disabled?: boolean;
147
  /** Whether this choice is pre-selected. Defaults to false */
148
  selected?: boolean;
149
}
150
```
151

152
**Usage Examples:**
153

154
```javascript
155
// Basic multiselect prompt
156
const response = await prompts({
157
  type: 'multiselect',
158
  name: 'technologies',
159
  message: 'Select technologies you use',
160
  choices: [
161
    { title: 'JavaScript', value: 'js' },
162
    { title: 'TypeScript', value: 'ts', selected: true },
163
    { title: 'Python', value: 'py' },
164
    { title: 'Java', value: 'java' },
165
    { title: 'C#', value: 'csharp' }
166
  ],
167
  max: 3,
168
  hint: '- Space to select. Return to submit'
169
});
170

171
// Multiselect with validation and formatting
172
const response = await prompts({
173
  type: 'multiselect',
174
  name: 'features',
175
  message: 'Select features to enable',
176
  choices: [
177
    { title: 'Authentication', value: 'auth', selected: true },
178
    { title: 'Database', value: 'db' },
179
    { title: 'File Upload', value: 'upload' },
180
    { title: 'Email Service', value: 'email' },
181
    { title: 'Premium Feature', value: 'premium', disabled: true }
182
  ],
183
  min: 1,
184
  instructions: 'Select at least one feature',
185
  format: values => values.map(v => v.toUpperCase())
186
});
187
```
188

189
### Autocomplete Prompt
190

191
Searchable selection prompt that filters choices based on user input. Users can type to search and navigate filtered results.
192

193
```javascript { .api }
194
{
195
  /** Prompt type identifier */
196
  type: 'autocomplete',
197
  /** Property name for response object */
198
  name: string,
199
  /** Display message for user */
200
  message: string,
201
  /** Array of choice objects for autocomplete */
202
  choices: Choice[],
203
  /** Function to filter choices based on input. Defaults to title-based filtering */
204
  suggest?: (input: string, choices: Choice[]) => Promise<Choice[]>,
205
  /** Maximum number of results to show. Defaults to 10 */
206
  limit?: number,
207
  /** Input style */
208
  style?: 'default' | 'password' | 'invisible' | 'emoji',
209
  /** Default initial value (string or choice index) */
210
  initial?: string | number,
211
  /** First ESCAPE keypress clears input if true */
212
  clearFirst?: boolean,
213
  /** Message when no matches found. Defaults to initial value */
214
  fallback?: string,
215
  /** Custom formatter for selected value */
216
  format?: (value: any, values: Answers) => any,
217
  /** Render callback with kleur styling */
218
  onRender?: (kleur: any) => void,
219
  /** State change callback */
220
  onState?: (state: { value: any; aborted: boolean; exited?: boolean }) => void,
221
  /** Input stream */
222
  stdin?: NodeJS.ReadableStream,
223
  /** Output stream */
224
  stdout?: NodeJS.WritableStream
225
}
226
```
227

228
**Usage Examples:**
229

230
```javascript
231
// Basic autocomplete prompt
232
const response = await prompts({
233
  type: 'autocomplete',
234
  name: 'actor',
235
  message: 'Pick your favorite actor',
236
  choices: [
237
    { title: 'Cage', value: 'nicolas-cage' },
238
    { title: 'Clooney', value: 'george-clooney' },
239
    { title: 'Gyllenhaal', value: 'jake-gyllenhaal' },
240
    { title: 'Gibson', value: 'mel-gibson' },
241
    { title: 'Grant', value: 'hugh-grant' }
242
  ]
243
});
244

245
// Autocomplete with custom suggest function
246
const countries = [
247
  { title: 'United States', value: 'US' },
248
  { title: 'United Kingdom', value: 'UK' },
249
  { title: 'Canada', value: 'CA' },
250
  { title: 'Germany', value: 'DE' },
251
  { title: 'France', value: 'FR' }
252
];
253

254
const response = await prompts({
255
  type: 'autocomplete',
256
  name: 'country',
257
  message: 'Select your country',
258
  choices: countries,
259
  suggest: (input, choices) => {
260
    return Promise.resolve(
261
      choices.filter(choice => 
262
        choice.title.toLowerCase().includes(input.toLowerCase()) ||
263
        choice.value.toLowerCase().includes(input.toLowerCase())
264
      )
265
    );
266
  },
267
  limit: 5,
268
  fallback: 'No country found'
269
});
270
```
271

272
### Autocomplete Multiselect Prompt
273

274
Searchable multiple-selection prompt combining the search capabilities of autocomplete with the multiple-selection of multiselect.
275

276
```javascript { .api }
277
{
278
  /** Prompt type identifier */
279
  type: 'autocompleteMultiselect',
280
  /** Property name for response object */
281
  name: string,
282
  /** Display message for user */
283
  message: string,
284
  /** Array of choice objects with optional pre-selection */
285
  choices: MultiselectChoice[],
286
  /** Maximum number of selections allowed */
287
  max?: number,
288
  /** Minimum number of selections required */
289
  min?: number,
290
  /** Hint text displayed to user */
291
  hint?: string,
292
  /** Warning message when selecting disabled option */
293
  warn?: string,
294
  /** Instructions text or boolean to show/hide default instructions */
295
  instructions?: string | boolean,
296
  /** Number of options to display per page. Defaults to 10 */
297
  optionsPerPage?: number,
298
  /** Custom formatter for selected values array */
299
  format?: (values: any[], allValues: Answers) => any,
300
  /** Render callback with kleur styling */
301
  onRender?: (kleur: any) => void,
302
  /** State change callback */
303
  onState?: (state: { value: any[]; aborted: boolean }) => void,
304
  /** Input stream */
305
  stdin?: NodeJS.ReadableStream,
306
  /** Output stream */
307
  stdout?: NodeJS.WritableStream
308
}
309
```
310

311
**Usage Examples:**
312

313
```javascript
314
// Searchable multiselect for large lists
315
const languages = [
316
  { title: 'JavaScript', value: 'js' },
317
  { title: 'TypeScript', value: 'ts' },
318
  { title: 'Python', value: 'py' },
319
  { title: 'Java', value: 'java' },
320
  { title: 'C++', value: 'cpp' },
321
  { title: 'C#', value: 'csharp' },
322
  { title: 'Go', value: 'go' },
323
  { title: 'Rust', value: 'rust' },
324
  { title: 'PHP', value: 'php' },
325
  { title: 'Ruby', value: 'ruby' }
326
];
327

328
const response = await prompts({
329
  type: 'autocompleteMultiselect',
330
  name: 'languages',
331
  message: 'Select programming languages',
332
  choices: languages,
333
  max: 5,
334
  hint: 'Type to search, space to select, return to submit'
335
});
336
```
337

338
## Choice Prompt Behavior
339

340
### Navigation Controls
341

342
**Select Prompt:**
343
- **Up/Down Arrow**: Navigate between choices
344
- **Tab**: Cycle through choices
345
- **Enter**: Select highlighted choice
346
- **Escape**: Cancel prompt
347

348
**Multiselect Prompt:**
349
- **Up/Down Arrow**: Navigate between choices
350
- **Space**: Toggle selection of current choice
351
- **Right Arrow**: Select current choice
352
- **Left Arrow**: Deselect current choice
353
- **Tab**: Cycle through choices
354
- **Enter**: Submit selected choices
355
- **Escape**: Cancel prompt
356

357
**Autocomplete Prompts:**
358
- **Type**: Filter choices by input
359
- **Up/Down Arrow**: Navigate filtered results
360
- **Tab**: Cycle through filtered results  
361
- **Page Up/Page Down**: Navigate pages (Mac: fn + Up/Down)
362
- **Enter**: Select highlighted choice
363
- **Escape**: Clear input (if clearFirst: true) or cancel
364

365
### Choice Configuration
366

367
```javascript { .api }
368
// Choice object properties
369
interface Choice {
370
  title: string;        // Required display text
371
  value?: any;          // Optional value (defaults to index)
372
  description?: string; // Optional description text
373
  disabled?: boolean;   // Optional disabled state
374
  selected?: boolean;   // Optional pre-selection (multiselect only)
375
}
376

377
// String choices are automatically converted to choice objects
378
const choices = ['Option 1', 'Option 2', 'Option 3'];
379
// Equivalent to:
380
const choices = [
381
  { title: 'Option 1', value: 0 },
382
  { title: 'Option 2', value: 1 },
383
  { title: 'Option 3', value: 2 }
384
];
385
```
386

387
### Custom Suggest Function
388

389
For autocomplete prompts, you can provide a custom filtering function:
390

391
```javascript { .api }
392
/**
393
 * Custom suggest function for filtering choices
394
 * @param input - User's search input
395
 * @param choices - Array of all available choices
396
 * @returns Promise resolving to filtered choices array
397
 */
398
type SuggestFunction = (
399
  input: string, 
400
  choices: Choice[]
401
) => Promise<Choice[]>;
402

403
// Example: case-insensitive search in title and value
404
const suggest = (input, choices) => {
405
  const filtered = choices.filter(choice => {
406
    const searchText = input.toLowerCase();
407
    return (
408
      choice.title.toLowerCase().includes(searchText) ||
409
      (choice.value && choice.value.toString().toLowerCase().includes(searchText))
410
    );
411
  });
412
  return Promise.resolve(filtered);
413
};
414
```
415

416
### Return Values
417

418
- **Select**: Returns the `value` property of selected choice (or index if no value)
419
- **Multiselect**: Returns array of `value` properties from selected choices
420
- **Autocomplete**: Returns the `value` property of selected choice (or index if no value)
421
- **Autocomplete Multiselect**: Returns array of `value` properties from selected choices