# Checklist Task

One step of an onboarding checklist that can be ticked off, with the next step to do highlighted.

- Category: Forms
- Page: https://wunderui.com/components/checklist-task
- Tier: Free

## Install

```bash
npx wunderui-cli add checklist-task
```

## Import

```tsx
import { ChecklistTask } from "@/components/blocks/application"
```

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import { ChecklistTask } from "@wunderui/react"

export function Step() {
  const [done, setDone] = useState(false)

  return (
    <ChecklistTask done={done} meta="3 min" onClick={() => setDone(!done)}>
      Create your first project
    </ChecklistTask>
  )
}
```

Expected result: You see one row with an empty circle, the label with 3 min under it and a chevron. Pressing it turns the circle green, adds a tick and dims the label.

## Usage

```tsx
import { useEffect, useRef, useState } from "react"
import { Button, ChecklistTask } from "@wunderui/react"

const TASKS = [
  { id: "profile", label: "Complete your profile", meta: "1 min" },
  { id: "invite", label: "Invite your team", meta: "Takes about 2 min" },
  { id: "project", label: "Create your first project", meta: "3 min" },
  { id: "repo", label: "Connect your repository", meta: "5 min" },
]

export function Checklist() {
  const [done, setDone] = useState(["profile"])
  const list = useRef<HTMLUListElement>(null)
  const focusId = useRef<string | null>(null)
  const next = TASKS.find((task) => !done.includes(task.id))
  const toggle = (id: string) => {
    focusId.current = id
    setDone((ids) => (ids.includes(id) ? ids.filter((item) => item !== id) : [...ids, id]))
  }

  useEffect(() => {
    if (!focusId.current) return
    list.current?.querySelector<HTMLElement>(`[data-task="${focusId.current}"] [role=checkbox]`)?.focus()
    focusId.current = null
  }, [done])

  return (
    <ul ref={list} aria-label="Getting started" className="flex flex-col gap-1">
      {TASKS.map((task) => {
        const isDone = done.includes(task.id)
        return (
          <li key={task.id} data-task={task.id}>
            <ChecklistTask
              done={isDone}
              current={task === next}
              meta={isDone ? undefined : task.meta}
              onClick={() => toggle(task.id)}
              action={
                <Button size="sm" variant="gradient" onClick={() => toggle(task.id)}>
                  Start
                </Button>
              }
            >
              {task.label}
            </ChecklistTask>
          </li>
        )
      })}
    </ul>
  )
}
```

## When to use

### Use Checklist Task for

- The steps of an onboarding, setup or getting-started checklist
- A list where one step is next and has its own button
- A short list of tasks that people tick and untick

### Use something else

- [Checkbox](https://wunderui.com/components/checkbox) for options in a form, with a label and a hint
- [Progress](https://wunderui.com/components/progress) for how far along something is, without naming the steps
- [List Item](https://wunderui.com/components/list-item) for a row that opens something, with a leading checkbox among other slots

## Keyboard

An open or done step is one tab stop, and the current step has two: its circle, then its action. Both are native buttons, so Enter and Space work on them.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the next or previous step. On the current step it visits the circle first and the action second. |
| `Space` or `Enter` | Toggles the focused step and calls `onClick`. On the current step, the circle toggles it and the action does whatever you gave it. |

Arrow keys do not move between steps. Build the steps as a list and let Tab walk through them.

## Behavior

What the row does with state, content, the DOM and motion.

- **Three states, two kinds of element:** An open or done step is one checkbox button. The current step is a block holding two buttons, the circle (Mark as done) and your action, and done and current can be set together.
- **Hover:** Hovering an open or done step fills the row lightly, and the circle of an open step turns indigo. The current step has no hover fill, because its action is the thing to press.
- **Focus:** Keyboard focus draws an indigo border with a 2 px ring around the row, or around the circle on the current step. The ring follows the rounded shape.
- **Long text:** The label and meta wrap and the row grows. The action keeps its size, so the text gives way, and a word without a break point is not cut.
- **Names for assistive technology:** An open or done step is named by its label followed by its meta. The current step's circle is always named Mark as done, so give the Start button its own label.
- **Focus after a tick:** A step that becomes or stops being current is rebuilt as another element, and the focused button disappears. Return focus to the checkbox of the step the person pressed.
- **Motion and reduced motion:** Colours of the row, circle and label change quickly, and the green tick scales in once with a fade. With reduced motion it only fades in, and the colours still change.

## Anatomy

- `ChecklistTask`: The row: 12 px side padding, 8 px radius and 12 px between its parts. A done or open step is one checkbox button, while the current step is a tinted block with two buttons.
- `Circle`: A 22 px circle: empty with a 1.5 px rim while open, indigo rim on the current step, solid green with a tick when done. On the current step it is its own checkbox button named Mark as done.
- `Label`: The label in 14 px medium text. It is quiet (tertiary) when the step is done and takes the tint of the row on the current step.
- `Meta`: The meta line under the label, in 12 px text, for example the time a step takes. It is shown in every state.
- `Action`: The action, usually a Start button, at the right of the current step. The other states do not render it.
- `Chevron`: A 16 px chevron at the right of an open step that is not current. A done step and the current step have none.

## Best practices

### When to use

- Use Checklist Task for the steps of an onboarding or setup checklist. For a plain list of options without a next step, use Checkbox Field.

### Do

- Mark exactly one step current and give it an action such as Start. Only the current step shows the action, and its circle becomes a checkbox button of its own.
- Handle the click as a toggle. It fires for open and done steps alike, so a step can be ticked and unticked again.
- Work out the current step from the list, as the first step that is not done, so it moves on by itself when a step is ticked.
- Put the steps in a list. Inside a panel with 8 px of padding and a 16 px radius, the 8 px row is concentric to the panel.
- After a tick, move focus back to the checkbox of the step that was pressed. The current step is rebuilt as another element, so a step that becomes or stops being current loses focus.

### Don't

- Don't pass an action to steps that are not current. It is not rendered there.
- Don't use a step for something that cannot be ticked yet. There is no disabled state, so leave the step out until it can be done.

## API reference

### ChecklistTask

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode |  | The label of the step. Required. |
| action | React.ReactNode |  | A button at the right of the current step, for example Start. Not rendered on a step that is not current. |
| className | string |  | Added to the row. Use it for the width or for spacing in a list. |
| current | boolean |  | Marks the step to do next: tinted row, circle as its own checkbox button, room for `action`. Use it on one step. |
| done | boolean |  | Draws a green circle with a tick and a quiet label, and sets `aria-checked`. Without it the step is open. |
| meta | React.ReactNode |  | A line under the label, for example how long the step takes. Shown in every state. |
| onClick | () => void |  | Toggles the step. On an open or done step it is the row; on the current step it is the circle. Called for ticking and unticking alike. |

## Examples

### State: open, current and done

```tsx
import { useState } from "react"
import { ChecklistTask } from "@wunderui/react"

export function Example() {
  const [done, setDone] = useState(false)

  return (
    <ChecklistTask
      done={done}
      meta="1 min"
      onClick={() => setDone(!done)}
    >
      Complete your profile
    </ChecklistTask>
  )
}
```

### Content: label, meta and action

```tsx
import { useState } from "react"
import { ChecklistTask } from "@wunderui/react"

export function Example() {
  const [done, setDone] = useState(false)

  return (
    <ChecklistTask
      done={done}
      onClick={() => setDone(!done)}
    >
      Create your first project
    </ChecklistTask>
  )
}
```

### Text: short, long and narrow

```tsx
import { useState } from "react"
import { Button, ChecklistTask } from "@wunderui/react"

export function Example() {
  const [done, setDone] = useState(false)

  return (
    <ChecklistTask
      current
      done={done}
      meta="Takes about 2 min"
      onClick={() => setDone(!done)}
      action={
        <Button size="sm" variant="gradient" onClick={() => setDone(true)}>
          Start
        </Button>
      }
    >
      Invite your team
    </ChecklistTask>
  )
}
```

## In context

### Getting started: the next step moves on

The first open step is the current one. Start or the row itself ticks it, the bar and count follow and the next step becomes current, and Reset starts again.

```tsx
import { useEffect, useRef, useState } from "react"
import { Button, ChecklistTask, Progress } from "@wunderui/react"

const TASKS = [
  { id: "profile", label: "Complete your profile", meta: "1 min" },
  { id: "invite", label: "Invite your team", meta: "Takes about 2 min" },
  { id: "project", label: "Create your first project", meta: "3 min" },
  { id: "repo", label: "Connect your repository", meta: "5 min" },
  { id: "billing", label: "Set up billing", meta: "2 min" },
]

export function GettingStarted() {
  const [done, setDone] = useState(["profile"])
  const list = useRef<HTMLUListElement>(null)
  const focusId = useRef<string | null>(null)
  const next = TASKS.find((task) => !done.includes(task.id))
  const percent = Math.round((done.length / TASKS.length) * 100)
  const toggle = (id: string) => {
    focusId.current = id
    setDone((ids) => (ids.includes(id) ? ids.filter((item) => item !== id) : [...ids, id]))
  }

  useEffect(() => {
    if (!focusId.current) return
    list.current?.querySelector<HTMLElement>(`[data-task="${focusId.current}"] [role=checkbox]`)?.focus()
    focusId.current = null
  }, [done])

  return (
    <section aria-label="Getting started" className="flex flex-col rounded-xl border border-border bg-card">
      <div className="flex flex-col gap-3 p-4">
        <div className="flex flex-col gap-0.5">
          <h3 className="text-base font-semibold text-foreground">Getting started</h3>
          <p className="text-xs text-text-secondary">
            {done.length} of {TASKS.length} steps completed
          </p>
        </div>
        <Progress value={percent} aria-label="Getting started progress" />
      </div>
      <ul ref={list} className="flex flex-col gap-1 p-2 pt-0">
        {TASKS.map((task) => {
          const isDone = done.includes(task.id)
          return (
            <li key={task.id} data-task={task.id}>
              <ChecklistTask
                done={isDone}
                current={task === next}
                meta={isDone ? undefined : task.meta}
                onClick={() => toggle(task.id)}
                action={
                  <Button size="sm" variant="gradient" onClick={() => toggle(task.id)}>
                    Start
                  </Button>
                }
              >
                {task.label}
              </ChecklistTask>
            </li>
          )
        })}
      </ul>
      {!next && <p className="mx-2 mb-2 rounded-md bg-tint-green px-3 py-2 text-xs font-medium text-tint-text-green">All steps are complete.</p>}
    </section>
  )
}
```

### Release checklist: a list without a current step

Every step is a plain row, so labels wrap in a narrow panel. One button ticks or clears every row, and Reset brings back the two ticked steps.

```tsx
import { useState } from "react"
import { Button, ChecklistTask } from "@wunderui/react"

const TASKS = [
  { id: "changelog", label: "Write the changelog entry for version 0.4.0" },
  { id: "tests", label: "Run the accessibility and snippet tests on every page that changed" },
  { id: "tokens", label: "Check that Figma variables and styles.css still match" },
  { id: "docs", label: "Update the component counts in the docs, the README and the llms files" },
  { id: "tag", label: "Tag the release and publish the packages" },
  { id: "announce", label: "Announce the release to the team in the product channel" },
]

export function ReleaseChecklist() {
  const [done, setDone] = useState(["changelog","tests"])
  const toggle = (id: string) => setDone((ids) => (ids.includes(id) ? ids.filter((item) => item !== id) : [...ids, id]))

  return (
    <section aria-label="Release checklist" className="flex flex-col gap-2 rounded-xl border border-border bg-card p-2">
      <div className="flex items-center justify-between gap-2 px-2 pt-1">
        <h3 className="text-sm font-semibold text-foreground">
          Release 0.4.0 · {done.length} of {TASKS.length}
        </h3>
        <Button size="sm" variant="plain" onClick={() => setDone(done.length === TASKS.length ? [] : TASKS.map((task) => task.id))}>
          {done.length === TASKS.length ? "Clear all" : "Check all"}
        </Button>
      </div>
      <ul className="flex flex-col gap-1">
        {TASKS.map((task) => (
          <li key={task.id}>
            <ChecklistTask done={done.includes(task.id)} onClick={() => toggle(task.id)}>
              {task.label}
            </ChecklistTask>
          </li>
        ))}
      </ul>
    </section>
  )
}
```

## For AI agents

`get_component("checklist-task")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
