<!-- Generated by scripts/gen-docs.mts from the JSDoc in registry/. Do not edit; run `pnpm run docs`. -->

# Checklist

A list of things to tick off, such as a recipe's ingredients or a shopping list: each row a checkbox the whole row toggles, with an optional value and action. Checking a row fills its box, draws its tick and then a strike through its label, and softens its text; rows enter and leave as `items` changes, and "Clear checked" shows while something is checked.

```tsx
import { Checklist } from "@/components/ouro/checklist/checklist";
```

## Example

```tsx
<Checklist
  label="Ingredients"
  items={[{ id: "oats", label: "rolled oats", value: "1 cup", checked: checked.has("oats") }]}
  onCheckedChange={(id, isChecked) => toggle(id, isChecked)}
  onClearChecked={clearAll}
/>
```

## Use instead when

- Use `CheckboxGroup` instead when the choices submit with a form; use `Checklist` for progress a person ticks off.

## Props

Type: `ChecklistProps`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Layout only: margins, width, grid placement (`mt-4`, `col-span-2`). Appearance classes warn in development; style checklists in your theme. |
| `clearLabel` | `string` | `"Clear checked"` | The clear button's text. Translate it here. |
| `description` | `ReactNode` |  | Supporting text under the label, read after it through `aria-describedby`. |
| `empty` | `ReactNode` |  | What shows when there are no rows: text, or an `Empty`. |
| `hideLabel` | `boolean` |  | Hides the label visually; screen readers still read it as the group's name. |
| `items` (required) | `readonly ChecklistItemData[]` |  | The rows, in order. Adding one brings it in; removing one lets it leave before it goes, and an id added back while its row leaves returns that row in place. |
| `label` (required) | `string` |  | What the list is ("Ingredients"), shown above the rows and read as the group's name. Required: a group needs a name. To hide it visually, keep it and add `hideLabel`. |
| `onCheckedChange` (required) | `(id: string, checked: boolean) => void` |  | Called with a row's id and its new state when it is checked or unchecked. Required: a checklist without it never changes. |
| `onClearChecked` | `(() => void)` |  | Shows a "Clear checked" button while something is checked, and is called when it is pressed. |
| `ref` | `Ref<HTMLDivElement>` |  | The group element, a `<div role="group">`. |

## Don't use

These are not props. Passing one fails the type check with the fix in the error, and in development a console message names the fix.

- `isChecked`: Not a prop. Each item says whether it is checked: `items={[{ id, label, checked: true }]}`.
- `legend`: Not a prop. A checklist is named by its `label`: `<Checklist label="Ingredients">`.
- `onChange`: Not a prop. Ouro UI uses `onCheckedChange`, which gets the row's id and its new state.
- `onCheck`: Not a prop. Ouro UI uses `onCheckedChange`, which gets the row's id and its new state.
- `onToggle`: Not a prop. Ouro UI uses `onCheckedChange`, which gets the row's id and its new state.

## `className` is for layout only

Pass margins, width and grid placement (`mt-4`, `w-full`, `col-span-2`).

Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (`hover:`, `sm:`) and any `!` are removed, it starts with `bg-`, `text-`, `border-`, `rounded-`, `shadow-`, `font-`, `ring-`, `from-`, `via-`, `to-`, `fill-` or `stroke-`, or is `border`, `rounded`, `shadow` or `ring`, or has a `dark:` variant. Text wrapping, overflow and table layout classes (`text-wrap`, `text-ellipsis`, `border-collapse`) are layout and do not warn.

Alignment classes (`text-center`) warn too: set alignment on a parent element.

## Parts

When these props cannot express your layout, build it from the parts in `@/components/ouro/checklist/checklist-parts`. See [parts.md](parts.md#checklist-parts) for the required nesting.

## Types

### `ChecklistItemData`

One row of a `Checklist`.

```ts
interface ChecklistItemData {
  /** Identifies the row: `onCheckedChange` gets it, and a row keeps its place and motion by it. */
  id: string;
  /** What to tick off, read as the row's checkbox name. */
  label: string;
  /** Supporting text under the label: a note, a substitution. */
  description?: ReactNode | undefined;
  /** Trailing text at the end of the row, such as an amount (`1 cup`) or a time; screen readers hear it after the label. */
  value?: ReactNode | undefined;
  /** Whether the row is checked. */
  checked: boolean;
  /** Disables the row's box and fades it. */
  disabled?: boolean | undefined;
  /** A control of the row's own beside it (a button, a menu), its own tab stop; clicking it does not toggle the row. */
  action?: ReactNode | undefined;
}
```