[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 `box`, `group`, and `group-multi-select` (#542)
authored by
Willow (GHOST)
and committed by
GitHub
(May 13, 2026, 10:20 AM -0500)
adb6af9f
3170ed94
+166
-4
+5
.changeset/giant-doors-rest.md
+5
.changeset/giant-doors-rest.md
+61
packages/prompts/src/box.ts
+61
packages/prompts/src/box.ts
···
16
16
S_CORNER_TOP_RIGHT,
17
17
} from './common.js';
18
18
19
+
/**
20
+
* Alignment for content or titles within the box.
21
+
*/
19
22
export type BoxAlignment = 'left' | 'center' | 'right';
20
23
21
24
type BoxSymbols = [topLeft: string, topRight: string, bottomLeft: string, bottomRight: string];
···
28
31
];
29
32
const squareSymbols: BoxSymbols = [S_BAR_START, S_BAR_START_RIGHT, S_BAR_END, S_BAR_END_RIGHT];
30
33
34
+
/**
35
+
* Options for the {@link box} prompt.
36
+
*/
31
37
export interface BoxOptions extends CommonOptions {
38
+
/**
39
+
* Alignment of the content (`'left'`, `'center'`, or `'right'`).
40
+
* @default 'left'
41
+
*/
32
42
contentAlign?: BoxAlignment;
43
+
44
+
/**
45
+
* Alignment of the title (`'left'`, `'center'`, or `'right'`).
46
+
* @default 'left'
47
+
*/
33
48
titleAlign?: BoxAlignment;
49
+
50
+
/**
51
+
* The width of the box, either `'auto'` to fit the content or a number for a fixed width.
52
+
* @default 'auto'
53
+
*/
34
54
width?: number | 'auto';
55
+
56
+
/**
57
+
* Padding around the title.
58
+
* @default 1
59
+
*/
35
60
titlePadding?: number;
61
+
62
+
/**
63
+
* Padding around the content.
64
+
* @default 2
65
+
*/
36
66
contentPadding?: number;
67
+
68
+
/**
69
+
* Use rounded corners when `true`, square corners when `false`.
70
+
* @default true
71
+
*/
37
72
rounded?: boolean;
73
+
74
+
/**
75
+
* Custom function to style the border characters.
76
+
*/
38
77
formatBorder?: (text: string) => string;
39
78
}
40
79
···
59
98
60
99
const defaultFormatBorder = (text: string) => text;
61
100
101
+
/**
102
+
* Renders a customizable box around text content. It's similar to {@link note} but offers
103
+
* more styling options.
104
+
*
105
+
* @see https://bomb.sh/docs/clack/packages/prompts/#box
106
+
*
107
+
* @param message - The content to display inside the box.
108
+
* @param title - The title to display in the top border of the box.
109
+
* @param opts - Optional configuration for the box styling and behavior.
110
+
*
111
+
* @example
112
+
* ```ts
113
+
* import { box } from '@clack/prompts';
114
+
*
115
+
* box('This is the content of the box', 'Box Title', {
116
+
* contentAlign: 'center',
117
+
* titleAlign: 'center',
118
+
* width: 'auto',
119
+
* rounded: true,
120
+
* });
121
+
* ```
122
+
*/
62
123
export const box = (message = '', title = '', opts?: BoxOptions) => {
63
124
const output: Writable = opts?.output ?? process.stdout;
64
125
const columns = getColumns(output);
+65
packages/prompts/src/group-multi-select.ts
+65
packages/prompts/src/group-multi-select.ts
···
12
12
import { limitOptions } from './limit-options.js';
13
13
import type { Option } from './select.js';
14
14
15
+
/**
16
+
* Options for the {@link groupMultiselect} prompt.
17
+
*/
15
18
export interface GroupMultiSelectOptions<Value> extends CommonOptions {
19
+
/**
20
+
* The message or question shown to the user above the input.
21
+
*/
16
22
message: string;
23
+
24
+
/**
25
+
* Grouped options to display. Each key is a group label, and each value is an array of options.
26
+
*/
17
27
options: Record<string, Option<Value>[]>;
28
+
29
+
/**
30
+
* The initially selected option(s).
31
+
*/
18
32
initialValues?: Value[];
33
+
34
+
/**
35
+
* The maximum number of items/options to display at once.
36
+
*/
19
37
maxItems?: number;
38
+
39
+
/**
40
+
* When `true` at least one option must be selected.
41
+
* @default true
42
+
*/
20
43
required?: boolean;
44
+
45
+
/**
46
+
* The value the cursor should be positioned at initially.
47
+
*/
21
48
cursorAt?: Value;
49
+
50
+
/**
51
+
* Whether entire groups can be selected at once.
52
+
* @default true
53
+
*/
22
54
selectableGroups?: boolean;
55
+
56
+
/**
57
+
* Number of blank lines between groups.
58
+
* @default 0
59
+
*/
23
60
groupSpacing?: number;
24
61
}
62
+
63
+
/**
64
+
* The `groupMultiselect` prompt extends the {@link multiselect} prompt to allow
65
+
* arranging distinct Multi-Selects, whilst keeping all of them interactive.
66
+
*
67
+
* @see https://bomb.sh/docs/clack/packages/prompts/#group-multiselect
68
+
*
69
+
* @example
70
+
* ```ts
71
+
* import { groupMultiselect } from '@clack/prompts';
72
+
*
73
+
* const result = await groupMultiselect({
74
+
* message: 'Define your project',
75
+
* options: {
76
+
* 'Testing': [
77
+
* { value: 'Jest', hint: 'JavaScript testing framework' },
78
+
* { value: 'Playwright', hint: 'End-to-end testing' },
79
+
* ],
80
+
* 'Language': [
81
+
* { value: 'js', label: 'JavaScript', hint: 'Dynamic typing' },
82
+
* { value: 'ts', label: 'TypeScript', hint: 'Static typing' },
83
+
* ],
84
+
* },
85
+
* });
86
+
* ```
87
+
*
88
+
* @param opts The options for the group multiselect prompt
89
+
*/
25
90
export const groupMultiselect = <Value>(opts: GroupMultiSelectOptions<Value>) => {
26
91
const { selectableGroups = true, groupSpacing = 0 } = opts;
27
92
const opt = (
+35
-4
packages/prompts/src/group.ts
+35
-4
packages/prompts/src/group.ts
···
4
4
[P in keyof T]: T[P];
5
5
} & {};
6
6
7
+
/**
8
+
* The return type of a {@link PromptGroup}.
9
+
* Resolves all prompt results, excluding the cancel symbol.
10
+
*/
7
11
export type PromptGroupAwaitedReturn<T> = {
8
12
[P in keyof T]: Exclude<Awaited<T[P]>, symbol>;
9
13
};
10
14
15
+
/**
16
+
* Options for the {@link group} utility.
17
+
*/
11
18
export interface PromptGroupOptions<T> {
12
19
/**
13
-
* Control how the group can be canceled
14
-
* if one of the prompts is canceled.
20
+
* Called when any one of the prompts is canceled.
15
21
*/
16
22
onCancel?: (opts: { results: Prettify<Partial<PromptGroupAwaitedReturn<T>>> }) => void;
17
23
}
18
24
25
+
/**
26
+
* A group of prompts to be displayed sequentially, with each prompt receiving
27
+
* the results of all previous prompts in the group.
28
+
*/
19
29
export type PromptGroup<T> = {
20
30
[P in keyof T]: (opts: {
21
31
results: Prettify<Partial<PromptGroupAwaitedReturn<Omit<T, P>>>>;
···
23
33
};
24
34
25
35
/**
26
-
* Define a group of prompts to be displayed
27
-
* and return a results of objects within the group
36
+
* The `group` utility provides a consistent way to combine a series of prompts,
37
+
* combining each answer into one object. Each prompt receives the results of
38
+
* all previously completed prompts, and are displayed sequentially.
39
+
*
40
+
* @see https://bomb.sh/docs/clack/packages/prompts/#group
41
+
*
42
+
* @example
43
+
* ```ts
44
+
* import { group, text, password } from '@clack/prompts';
45
+
*
46
+
* const account = await group({
47
+
* email: () => text({
48
+
* message: 'What is your email address?',
49
+
* }),
50
+
* username: ({ results }) => text({
51
+
* message: 'What is your username?',
52
+
* placeholder: results.email?.replace(/@.+$/, '').toLowerCase() ?? '',
53
+
* }),
54
+
* password: () => password({
55
+
* message: 'Define your password',
56
+
* }),
57
+
* });
58
+
* ```
28
59
*/
29
60
export const group = async <T>(
30
61
prompts: PromptGroup<T>,