Skip to content

docs: update box, group, and group-multi-select sections #41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ghostdevv wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: update box, group, and group-multi-select sections #41

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 30 additions & 17 deletions src/content/docs/clack/packages/prompts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -454,6 +454,8 @@ Options:

### Group Multiselect

The `groupMultiselect` prompt extends the [`multiselect`](#multiple-values) prompt to allow arranging distinct Multi-Selects, whilst keeping all of them interactive.

```ts twoslash
// @errors: 2353
import { groupMultiselect } from '@clack/prompts';
Expand Down Expand Up @@ -491,7 +493,7 @@ const projectOptions = await groupMultiselect({
```

<pre class="cli-preview"><font color="#555753">│</font>
<font color="#06989A">◆</font> Define your project
<font color="#06989A">◆</font> Define your project
<font color="#06989A">│</font> <font color="#4E9A06">◼</font> Testing
<font color="#06989A">│</font> │ <font color="#4E9A06">◼</font> Jest (JavaScript testing framework)
<font color="#06989A">│</font> │ <font color="#4E9A06">◼</font> Playwright (End-to-end testing)
Expand All @@ -508,15 +510,21 @@ const projectOptions = await groupMultiselect({
<font color="#06989A">│</font> └ <font color="#4E9A06">◼</font> Biome.js (Formatter and linter)
<font color="#06989A">└</font></pre>

The `groupMultiselect` prompt supports two additional options:
- `groupSpacing`: An integer that specifies how many new lines to add between each group. This helps improve readability when you have many groups.
- `selectableGroups`: A boolean that determines whether top-level groups can be selected. When set to `false`, only individual items within groups can be selected.
Options:

- `message`: The message or question shown to the user above the input.
- `options`: Grouped options to display. Each key is a group label, and each value is an array of options.
- `initialValues`: The initially selected option(s).
- `maxItems`: The maximum number of items/options to display at once.
- `required`: When `true` at least one option must be selected (default: `true`).
- `cursorAt`: The value the cursor should be positioned at initially.
- `selectableGroups`: Whether entire groups can be selected at once (default: `true`).
- `groupSpacing`: Number of blank lines between groups (default: `0`).
- All [Common Options](#common-options)

### Group

The `group` function provides a convenient API for combining a series of questions.
Each question receives the `results` of previous answers.
The `group` function returns an object containing the result of every question.
The `group` utility provides a consistent way to combine a series of prompts, combining each answer into one object. Each prompt receives the results of all previously completed prompts, and are executed sequentially.

```ts twoslash
import { group, text, password } from '@clack/prompts';
Expand All @@ -543,16 +551,20 @@ const account = await group({
```

<pre class="cli-preview"><font color="#555753">│</font>
<font color="#4E9A06">◇</font> What is your email address?
<font color="#4E9A06">◇</font> What is your email address?
<font color="#555753">│</font> user.name@example.com
<font color="#555753">│</font>
<font color="#4E9A06">◇</font> What is your username?
<font color="#4E9A06">◇</font> What is your username?
<font color="#555753">│</font> bomb_sh
<font color="#555753">│</font>
<font color="#06989A">◆</font> Define your password
<font color="#06989A">◆</font> Define your password
<font color="#06989A">│</font> ▪▪▪▪▪▪▪▪▪▪▪▪<span style="background-color:#FFFFFF"><font color="#FFFFFF">_</font></span>
<font color="#06989A">└</font></pre>

Options:

- `onCancel`: Called when any one of the prompts is canceled.

### Tasks

The `tasks` function provides a convenient API for sequencing several asynchronous actions one after the other.
Expand Down Expand Up @@ -859,13 +871,14 @@ box('This is the content of the box', 'Box Title', {
<font color="#555753">│</font> <font color="#555753">╰──────────────────────────────╯</font></pre>

Options:
- `contentAlign`: Alignment of the content (`'left'`, `'center'`, or `'right'`)
- `titleAlign`: Alignment of the title (`'left'`, `'center'`, or `'right'`)
- `width`: Box width - use `'auto'` to fit content or a number for fixed width
- `titlePadding`: Padding around the title
- `contentPadding`: Padding around the content
- `rounded`: Use rounded corners when `true` (default), square corners when `false`
- `formatBorder`: Custom function to style the border characters

- `contentAlign`: Alignment of the content (`'left'`, `'center'`, or `'right'`. default `'left'`).
- `titleAlign`: Alignment of the title (`'left'`, `'center'`, or `'right'`. default `'left'`).
- `width`: The width of the box, either `'auto'` to fit the content or a number for a fixed width (default: `'auto'`).
- `titlePadding`: Padding around the title (default: `1`).
- `contentPadding`: Padding around the content (default: `2`).
- `rounded`: Use rounded corners when `true` (default), square corners when `false` (default: `true`).
- `formatBorder`: Custom function to style the border characters.

### Task Log

Expand Down