# Checklist

A titled list of tasks with a progress bar, such as the getting started steps on a dashboard. Each task has a checkbox, or a status icon when the app decides what is done. Use Stepper for a flow the user must follow in order.

**Dependencies:** npm: 1 direct, 5 total; registry: 4 direct, 6 total.

## Usage

### When to use

- Show the tasks that set up a workspace or account, and how many are done.
- Track a short list of tasks the user ticks off, such as the checks before a launch.

### When not to use

- Walk through steps that must happen in order. Use Stepper.
- Pick several options in a form. Use Checkbox.
- Show how far a single operation has run. Use Progress.

## Variants

### headingLevel

The heading level of the title: one below the heading the checklist sits under.

Values: `2`, `3`, `4`. Default: `3`.

## Examples

### Getting started

```tsx
<Checklist title="Set up your workspace" description="Finish these to get the most out of your dashboard." items={setupTasks} defaultValue={setupDone} />
```

### Read only, with actions

The app marks each task done. Open tasks show an action that starts them.

```tsx
<Checklist readOnly title="Set up your workspace" items={setupTaskActions} value={setupDone} />
```

### Without progress

```tsx
<Checklist showProgress={false} title="Before launch" items={launchTasks} defaultValue={launchDone} />
```

## Do and don't

### Do

- Keep it to 3 to 7 tasks, each a short verb phrase.
- Use readOnly when the app can tell a task is done, and give each open task an action that starts it.
- Hide the checklist once every task is done, or let the user dismiss it.

### Don't

- Do not use for steps that must happen in order. Use Stepper.
- Do not use for a set of options. Use Checkbox in a Field.
- Do not move finished tasks to the end; the list keeps its order.

## Props

| Name | Type | Values | Default | Description |
| --- | --- | --- | --- | --- |
| `title` (required) | `node` |  |  | The heading of the checklist. |
| `description` | `string` |  |  | Optional text under the title. |
| `items` (required) | `{ id: string; label: string; description?: string; action?: React.ReactNode; disabled?: boolean }[]` |  |  | The tasks in order. action shows after the text while the task is open. |
| `value` | `string[]` |  |  | Ids of the finished tasks, for a controlled checklist. |
| `defaultValue` | `string[]` |  |  | Ids of the tasks finished at first render, for an uncontrolled checklist. |
| `onValueChange` | `(value: string[]) => void` |  |  | Called with the finished ids, in item order, when a checkbox changes. |
| `readOnly` | `boolean` |  | `false` | The app decides when a task is done (a profile photo exists, a teammate joined). Tasks show a status icon instead of a checkbox. |
| `showProgress` | `boolean` |  | `true` | Shows the progress text and bar in the header. |
| `progressText` | `(done: number, total: number) => string` |  |  | The text above the bar, which also names it. Default EN `{done} of {total} done`, VI `Đã xong {done}/{total}`. |
| `headingLevel` | `enum` | `2`, `3`, `4` | `3` | The heading level of the title: one below the heading the checklist sits under. |
| `labels` | `{ done?: string; notDone?: string }` |  |  | Words read after each read-only task. Defaults: done, not done. Vietnamese: đã xong, chưa xong. |

## Anatomy

| Part | Description |
| --- | --- |
| `root` | The section: header over the list. |
| `header` | The title, the description and the progress bar. |
| `title` | The heading that names the checklist. |
| `description` | Optional text under the title. |
| `list` | The ul of tasks. |
| `item` | One task: control, label and description, then an optional action at the end. A line splits it from the task above. |
| `control` | The checkbox, or the status icon of a read-only task, in a box one line tall. |
| `icon` | The status icon of a read-only task: a dashed circle while open, a filled check circle in the success color when done. 16px. |
| `label` | The task name. Steps down to secondary text when done. |
| `itemDescription` | Optional second line under the task name. |
| `action` | Optional control after the text, such as a small Button. Shown only while the task is open. |

## Accessibility

Role: `region`

| Keys | Action |
| --- | --- |
| `Tab` | Moves to the next task's checkbox, then to its action, if any. |
| `Space` | Marks the focused task done or not done. |

- A section named by its title through aria-labelledby, with the tasks in a list.
- Each checkbox is named by its task label and described by the task description.
- The progress bar is named by the progress text (EN `2 of 5 done`) and reports the share as a percentage.
- A read-only task shows a status icon hidden from screen readers; its label ends with the word from labels (EN `done` or `not done`, VI `đã xong` or `chưa xong`).
- A finished task keeps its label and place; only its color steps down, so the list does not move.

## Install

```bash
npx werewolf-ui add checklist
```

Run `npx werewolf-ui init` once in your app before adding components. Init sets up tokens, their CSS import and agent rules. Add installs this component and its dependencies while preserving your theme. See [Installation](https://www.werewolf-ui.dev/docs/installation.md) for requirements and the alternative registry setup.