[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 `text`, `password`, and `multiline` prompts (#523)
Co-authored-by: paul valladares <85648028+dreyfus92@users.noreply.github.com>
authored by
Willow (GHOST)
paul valladares
and committed by
GitHub
(May 11, 2026, 6:54 PM -0500)
aab46a2a
54be8d7a
+112
-2
+5
.changeset/five-chicken-hide.md
+5
.changeset/five-chicken-hide.md
+2
-2
packages/prompts/README.md
+2
-2
packages/prompts/README.md
···
65
65
66
66
### Password
67
67
68
-
The password component behaves like `text`, but masks the input as the user types.
68
+
The password prompt behaves like the [`text`](#text) prompt, but masks the input as the user types.
69
69
70
70
```js
71
71
import { password } from '@clack/prompts';
···
201
201
202
202
### Multi-Line Text
203
203
204
-
The multi-line text component accepts multiple lines of text input. By default, pressing `Enter` twice submits the input.
204
+
The multi-line prompt accepts multiple lines of text input. By default, pressing `Enter` twice submits the input.
205
205
206
206
```js
207
207
import { multiline } from '@clack/prompts';
+26
packages/prompts/src/multi-line.ts
+26
packages/prompts/src/multi-line.ts
···
3
3
import { S_BAR, S_BAR_END, symbol } from './common.js';
4
4
import type { TextOptions } from './text.js';
5
5
6
+
/**
7
+
* Options for the {@link multiline} prompt
8
+
*/
6
9
export interface MultiLineOptions extends TextOptions {
10
+
/**
11
+
* When enabled it shows a `[ submit ]` button that can be focused with tab.
12
+
* By default, pressing `Enter` twice submits the input
13
+
*
14
+
* @default false
15
+
*/
7
16
showSubmit?: boolean;
8
17
}
9
18
19
+
/**
20
+
* The multi-line prompt accepts multiple lines of text input.
21
+
* By default, pressing `Enter` twice submits the input.
22
+
*
23
+
* @see https://bomb.sh/docs/clack/packages/prompts/#multi-line-text
24
+
*
25
+
* @example
26
+
* ```ts
27
+
* import { multiline } from '@clack/prompts';
28
+
*
29
+
* const bio = await multiline({
30
+
* message: 'Enter your bio',
31
+
* placeholder: 'Tell us about yourself...',
32
+
* showSubmit: true,
33
+
* });
34
+
* ```
35
+
*/
10
36
export const multiline = (opts: MultiLineOptions) => {
11
37
return new MultiLinePrompt({
12
38
validate: opts.validate,
+36
packages/prompts/src/password.ts
+36
packages/prompts/src/password.ts
···
2
2
import { PasswordPrompt, settings } from '@clack/core';
3
3
import { type CommonOptions, S_BAR, S_BAR_END, S_PASSWORD_MASK, symbol } from './common.js';
4
4
5
+
/**
6
+
* Options for the {@link password} prompt
7
+
*/
5
8
export interface PasswordOptions extends CommonOptions {
9
+
/**
10
+
* The prompt message or question shown to the user above the input.
11
+
*/
6
12
message: string;
13
+
14
+
/**
15
+
* Character to use for masking input.
16
+
* @default ▪/•
17
+
*/
7
18
mask?: string;
19
+
20
+
/**
21
+
* A function that validates user input. Return a `string` or `Error` to show as a
22
+
* validation error, or `undefined` to accept the result.
23
+
*/
8
24
validate?: (value: string | undefined) => string | Error | undefined;
25
+
26
+
/**
27
+
* When enabled it causes the input to be cleared if/when validation fails.
28
+
* @default false
29
+
*/
9
30
clearOnError?: boolean;
10
31
}
32
+
33
+
/**
34
+
* The password prompt behaves like the {@link text} prompt, but the input is masked.
35
+
*
36
+
* @see https://bomb.sh/docs/clack/packages/prompts/#password-input
37
+
*
38
+
* @example
39
+
* ```ts
40
+
* import { password } from '@clack/prompts';
41
+
*
42
+
* const result = await password({
43
+
* message: 'Enter your password',
44
+
* });
45
+
* ```
46
+
*/
11
47
export const password = (opts: PasswordOptions) => {
12
48
return new PasswordPrompt({
13
49
validate: opts.validate,
+43
packages/prompts/src/text.ts
+43
packages/prompts/src/text.ts
···
2
2
import { settings, TextPrompt } from '@clack/core';
3
3
import { type CommonOptions, S_BAR, S_BAR_END, symbol } from './common.js';
4
4
5
+
/**
6
+
* Options for the {@link text} prompt
7
+
*/
5
8
export interface TextOptions extends CommonOptions {
9
+
/**
10
+
* The prompt message or question shown to the user above the input.
11
+
*/
6
12
message: string;
13
+
14
+
/**
15
+
* A visual hint shown when the field has no content.
16
+
*/
7
17
placeholder?: string;
18
+
19
+
/**
20
+
* A fallback value returned when the user provides nothing (empty input).
21
+
*/
8
22
defaultValue?: string;
23
+
24
+
/**
25
+
* The starting value shown when the prompt first renders.
26
+
* Users can edit this value before submitting.
27
+
*/
9
28
initialValue?: string;
29
+
30
+
/**
31
+
* A function that validates user input. Return a `string` or `Error` to show as a
32
+
* validation error, or `undefined` to accept the result.
33
+
*/
10
34
validate?: (value: string | undefined) => string | Error | undefined;
11
35
}
12
36
37
+
/**
38
+
* The text prompt accepts a single line of text.
39
+
*
40
+
* @see https://bomb.sh/docs/clack/packages/prompts/#text-input
41
+
*
42
+
* @example
43
+
* ```ts
44
+
* import { text } from '@clack/prompts';
45
+
*
46
+
* const name = await text({
47
+
* message: 'What is your name?',
48
+
* placeholder: 'John Doe',
49
+
* validate: (value) => {
50
+
* if (!value || value.length < 2) return 'Name must be at least 2 characters';
51
+
* return undefined;
52
+
* },
53
+
* });
54
+
* ```
55
+
*/
13
56
export const text = (opts: TextOptions) => {
14
57
return new TextPrompt({
15
58
validate: opts.validate,