Components
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.
Preview
import { Checklist } from "@/components/ui/checklist"
const setupTasks = [
{ id: "profile", label: "Add a profile photo", description: "Helps your team recognize you." },
{ id: "invite", label: "Invite your team", description: "Work on dashboards together." },
{ id: "connect", label: "Connect a data source", description: "Import events from your app." },
{ id: "dashboard", label: "Create your first dashboard" },
]
const setupDone = ["profile"]
<Checklist description="Finish these to get the most out of your dashboard." title="Set up your workspace" items={setupTasks} defaultValue={setupDone} className="w-96 max-w-full" />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.
Examples
Getting started
import { Checklist } from "@/components/ui/checklist"
const setupTasks = [
{ id: "profile", label: "Add a profile photo", description: "Helps your team recognize you." },
{ id: "invite", label: "Invite your team", description: "Work on dashboards together." },
{ id: "connect", label: "Connect a data source", description: "Import events from your app." },
{ id: "dashboard", label: "Create your first dashboard" },
]
const setupDone = ["profile"]
<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.
import { Button } from "@/components/ui/button"
import { Checklist } from "@/components/ui/checklist"
const setupTaskActions = [
{ id: "profile", label: "Add a profile photo", action: <Button size="sm" variant="secondary">Upload</Button> },
{ id: "invite", label: "Invite your team", action: <Button size="sm" variant="secondary">Invite</Button> },
{ id: "connect", label: "Connect a data source", action: <Button size="sm" variant="secondary">Connect</Button> },
{ id: "dashboard", label: "Create your first dashboard", action: <Button size="sm" variant="secondary">Create</Button> },
]
const setupDone = ["profile"]
<Checklist readOnly title="Set up your workspace" items={setupTaskActions} value={setupDone} />Without progress
import { Checklist } from "@/components/ui/checklist"
const launchTasks = [
{ id: "domain", label: "Point the domain at the site" },
{ id: "copy", label: "Proofread the pricing page" },
{ id: "analytics", label: "Turn on analytics" },
]
const launchDone = ["domain"]
<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
npx werewolf-ui add checklistRun 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 for requirements and the alternative registry setup.