[READ-ONLY] Mirror of https://github.com/bombshell-dev/clack. Effortlessly build beautiful command-line apps
bomb.sh/docs/clack/basics/getting-started/
cli
command-line
command-line-app
node
prompt
prompts
docs: add jsdoc for `autocomplete`, `confirm`, and `path` prompts (#540)
authored by
Willow (GHOST)
and committed by
GitHub
(May 13, 2026, 10:00 AM -0500)
3170ed94
03c76044
+192
-17
+5
.changeset/yellow-bats-listen.md
+5
.changeset/yellow-bats-listen.md
+24
-3
packages/prompts/README.md
+24
-3
packages/prompts/README.md
···
81
81
82
82
### Confirm
83
83
84
-
The confirm component accepts a yes or no answer. The result is a boolean value of `true` or `false`.
84
+
The `confirm` prompt accepts a yes or no choice, returning a boolean value corresponding to the user's selection.
85
85
86
86
```js
87
87
import { confirm } from '@clack/prompts';
···
125
125
126
126
### Autocomplete
127
127
128
-
The autocomplete component lets a user filter a list by typing, then choose one option from the matching results. By default, matching uses each option's `label`, `hint`, and `value`. The result is the selected option's `value`.
128
+
The `autocomplete` prompt combines text input with a searchable list of options. It's perfect for when you have a large list of options and want to help users find what they're looking for quickly.
129
129
130
130
```js
131
131
import { autocomplete } from '@clack/prompts';
···
139
139
{ value: 'sveltekit', label: 'SvelteKit' },
140
140
{ value: 'remix', label: 'Remix' },
141
141
],
142
+
});
143
+
```
144
+
145
+
### Autocomplete Multi-Select
146
+
147
+
The `autocompleteMultiselect` prompt combines the search functionality of [autocomplete](#autocomplete) with the ability to select multiple options.
148
+
149
+
```js
150
+
import { autocomplete } from '@clack/prompts';
151
+
152
+
const framework = await autocomplete({
153
+
message: 'Search for a framework',
154
+
options: [
155
+
{ value: 'next', label: 'Next.js', hint: 'React framework' },
156
+
{ value: 'astro', label: 'Astro', hint: 'Content-focused' },
157
+
{ value: 'svelte', label: 'SvelteKit', hint: 'Compile-time framework' },
158
+
{ value: 'remix', label: 'Remix', hint: 'Full stack framework' },
159
+
{ value: 'nuxt', label: 'Nuxt', hint: 'Vue framework' },
160
+
],
161
+
placeholder: 'Type to search...',
162
+
maxItems: 5,
142
163
});
143
164
```
144
165
···
226
247
227
248
### Path
228
249
229
-
The path component offers filesystem path suggestions and returns the selected path as a string. When `directory: true` is set, only directories can be selected.
250
+
The `path` prompt extends [`autocomplete`](#autocomplete) to provide file and directory suggestions.
230
251
231
252
```js
232
253
import { path } from '@clack/prompts';
+76
-13
packages/prompts/src/autocomplete.ts
+76
-13
packages/prompts/src/autocomplete.ts
···
41
41
return results;
42
42
}
43
43
44
+
/**
45
+
* Options for the {@link autocomplete} prompt.
46
+
*/
44
47
interface AutocompleteSharedOptions<Value> extends CommonOptions {
45
48
/**
46
-
* The message to display to the user.
49
+
* The message or question shown to the user above the input.
47
50
*/
48
51
message: string;
52
+
49
53
/**
50
-
* Available options for the autocomplete prompt.
54
+
* The options to present, or a function that returns the options to present
55
+
* allowing for custom search/filtering.
56
+
*
57
+
* @see https://bomb.sh/docs/clack/packages/prompts/#dynamic-options-getter
51
58
*/
52
59
options: Option<Value>[] | ((this: AutocompletePrompt<Option<Value>>) => Option<Value>[]);
60
+
53
61
/**
54
-
* Maximum number of items to display at once.
62
+
* The maximum number of items/options to display in the autocomplete list at once.
55
63
*/
56
64
maxItems?: number;
65
+
57
66
/**
58
-
* Placeholder text to display when no input is provided.
67
+
* Placeholder text displayed when the search field is empty. When set, pressing
68
+
* tab copies the placeholder into the input.
59
69
*/
60
70
placeholder?: string;
71
+
61
72
/**
62
-
* Validates the value
73
+
* A function that validates user input. Return a `string` or `Error` to show as a
74
+
* validation error, or `undefined` to accept the result.
63
75
*/
64
76
validate?: (value: Value | Value[] | undefined) => string | Error | undefined;
77
+
65
78
/**
66
-
* Custom filter function to match options against search input.
67
-
* If not provided, a default filter that matches label, hint, and value is used.
79
+
* Custom filter function to match options against the search input.
68
80
*/
69
81
filter?: (search: string, option: Option<Value>) => boolean;
70
82
}
71
83
72
84
export interface AutocompleteOptions<Value> extends AutocompleteSharedOptions<Value> {
73
85
/**
74
-
* The initial selected value.
86
+
* The initially selected option from the list.
75
87
*/
76
88
initialValue?: Value;
89
+
77
90
/**
78
-
* The initial user input
91
+
* The starting value shown in the users input box.
79
92
*/
80
93
initialUserInput?: string;
81
94
}
82
95
96
+
/**
97
+
* The `autocomplete` prompt combines a text input with a searchable list of options.
98
+
* It's perfect for when you have a large list of options and want to help users
99
+
* find what they're looking for quickly.
100
+
*
101
+
* @see https://bomb.sh/docs/clack/packages/prompts/#autocomplete
102
+
*
103
+
* @example
104
+
* ```ts
105
+
* import { autocomplete } from '@clack/prompts';
106
+
*
107
+
* const framework = await autocomplete({
108
+
* message: 'Search for a framework',
109
+
* options: [
110
+
* { value: 'next', label: 'Next.js', hint: 'React framework' },
111
+
* { value: 'astro', label: 'Astro', hint: 'Content-focused' },
112
+
* { value: 'svelte', label: 'SvelteKit', hint: 'Compile-time framework' },
113
+
* { value: 'remix', label: 'Remix', hint: 'Full stack framework' },
114
+
* { value: 'nuxt', label: 'Nuxt', hint: 'Vue framework' },
115
+
* ],
116
+
* placeholder: 'Type to search...',
117
+
* maxItems: 5,
118
+
* });
119
+
* ```
120
+
*/
83
121
export const autocomplete = <Value>(opts: AutocompleteOptions<Value>) => {
84
122
const prompt = new AutocompletePrompt({
85
123
options: opts.options,
···
223
261
return prompt.prompt() as Promise<Value | symbol>;
224
262
};
225
263
226
-
// Type definition for the autocompleteMultiselect component
264
+
/**
265
+
* Options for the {@link autocompleteMultiselect} prompt
266
+
*/
227
267
export interface AutocompleteMultiSelectOptions<Value> extends AutocompleteSharedOptions<Value> {
228
268
/**
229
-
* The initial selected values
269
+
* The initially selected option(s) from the list.
230
270
*/
231
271
initialValues?: Value[];
272
+
232
273
/**
233
-
* If true, at least one option must be selected
274
+
* When `true` at least one option must be selected.
275
+
* @default false
234
276
*/
235
277
required?: boolean;
236
278
}
237
279
238
280
/**
239
-
* Integrated autocomplete multiselect - combines type-ahead filtering with multiselect in one UI
281
+
* The `autocompleteMultiselect` prompt combines the search functionality of autocomplete
282
+
* with the ability to select multiple options.
283
+
*
284
+
* @see https://bomb.sh/docs/clack/packages/prompts/#autocomplete-multiselect
285
+
*
286
+
* @example
287
+
* ```ts
288
+
* import { autocompleteMultiselect } from '@clack/prompts';
289
+
*
290
+
* const frameworks = await autocompleteMultiselect({
291
+
* message: 'Select frameworks',
292
+
* options: [
293
+
* { value: 'next', label: 'Next.js', hint: 'React framework' },
294
+
* { value: 'astro', label: 'Astro', hint: 'Content-focused' },
295
+
* { value: 'svelte', label: 'SvelteKit', hint: 'Compile-time framework' },
296
+
* { value: 'remix', label: 'Remix', hint: 'Full stack framework' },
297
+
* { value: 'nuxt', label: 'Nuxt', hint: 'Vue framework' },
298
+
* ],
299
+
* placeholder: 'Type to search...',
300
+
* maxItems: 5,
301
+
* });
302
+
* ```
240
303
*/
241
304
export const autocompleteMultiselect = <Value>(opts: AutocompleteMultiSelectOptions<Value>) => {
242
305
const formatOption = (
+42
packages/prompts/src/confirm.ts
+42
packages/prompts/src/confirm.ts
···
9
9
symbol,
10
10
} from './common.js';
11
11
12
+
/**
13
+
* Options for the {@link confirm} prompt.
14
+
*/
12
15
export interface ConfirmOptions extends CommonOptions {
16
+
/**
17
+
* The message or question shown to the user above the input.
18
+
*/
13
19
message: string;
20
+
21
+
/**
22
+
* The label to use for the active (true) option.
23
+
* @default 'Yes'
24
+
*/
14
25
active?: string;
26
+
27
+
/**
28
+
* The label to use for the inactive (false) option.
29
+
* @default 'No'
30
+
*/
15
31
inactive?: string;
32
+
33
+
/**
34
+
* The initial selected value (true or false).
35
+
* @default true
36
+
*/
16
37
initialValue?: boolean;
38
+
39
+
/**
40
+
* Whether to render the options vertically instead of horizontally.
41
+
* @default false
42
+
*/
17
43
vertical?: boolean;
18
44
}
45
+
46
+
/**
47
+
* The `confirm` prompt accepts a yes or no choice, returning a boolean value
48
+
* corresponding to the user's selection.
49
+
*
50
+
* @see https://bomb.sh/docs/clack/packages/prompts/#confirmation
51
+
*
52
+
* @example
53
+
* ```ts
54
+
* import { confirm } from '@clack/prompts';
55
+
*
56
+
* const shouldProceed = await confirm({
57
+
* message: 'Do you want to continue?',
58
+
* });
59
+
* ```
60
+
*/
19
61
export const confirm = (opts: ConfirmOptions) => {
20
62
const active = opts.active ?? 'Yes';
21
63
const inactive = opts.inactive ?? 'No';
+45
-1
packages/prompts/src/path.ts
+45
-1
packages/prompts/src/path.ts
···
3
3
import { autocomplete } from './autocomplete.js';
4
4
import type { CommonOptions } from './common.js';
5
5
6
+
/**
7
+
* Options for the {@link path} prompt.
8
+
*/
6
9
export interface PathOptions extends CommonOptions {
10
+
/**
11
+
* The message or question shown to the user above the input.
12
+
*/
13
+
message: string;
14
+
15
+
/**
16
+
* The starting directory for path suggestions (defaults to current working directory).
17
+
*/
7
18
root?: string;
19
+
20
+
/**
21
+
* When `true` only **directories** appear in suggestions while you navigate.
22
+
*/
8
23
directory?: boolean;
24
+
25
+
/**
26
+
* The starting path shown when the prompt first renders, which users can edit
27
+
* before submitting. If not provided it will fall back to the given `root`,
28
+
* or the current working directory.
29
+
*
30
+
* In `directory` mode, if the initial value points to a directory that exists,
31
+
* pressing enter will submit the input instead of jumping to the first child.
32
+
*/
9
33
initialValue?: string;
10
-
message: string;
34
+
35
+
/**
36
+
* A function that validates the given path. Return a `string` or `Error` to show as a
37
+
* validation error, or `undefined` to accept the result.
38
+
*/
11
39
validate?: (value: string | undefined) => string | Error | undefined;
12
40
}
13
41
42
+
/**
43
+
* The `path` prompt extends `autocomplete` to provide file and directory suggestions.
44
+
*
45
+
* @see https://bomb.sh/docs/clack/packages/prompts/#path-selection
46
+
*
47
+
* @example
48
+
* ```ts
49
+
* import { path } from '@clack/prompts';
50
+
*
51
+
* const result = await path({
52
+
* message: 'Select a file:',
53
+
* root: process.cwd(),
54
+
* directory: false,
55
+
* });
56
+
* ```
57
+
*/
14
58
export const path = (opts: PathOptions) => {
15
59
const validate = opts.validate;
16
60