# Checkbox list (goodtabs UI)

A bordered list of checkbox rows with a select all header and mono meta.

## Install

```bash
npx shadcn@latest add https://ui.goodtabs.co/r/checkbox-list.json
```

Or, with the @goodtabs namespace configured in components.json: `npx shadcn@latest add @goodtabs/checkbox-list`

## Usage

```tsx
import { CheckboxList } from "@/components/ui/checkbox-list"

<CheckboxList
  aria-label="Repositories"
  items={[{ id: "ui", label: "goodtabs/ui", meta: "12 PRs" }]}
  value={selected}
  onValueChange={setSelected}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| items | `{ id: string; label: ReactNode; meta?: ReactNode; disabled?: boolean }[]` |  | The rows. meta is mono text on the right. |
| value | `string[]` |  | Controlled list of checked ids. |
| defaultValue | `string[]` | `[]` | Starting checked ids. |
| onValueChange | `(value: string[]) => void` |  | Fires with the full list of checked ids. |
| selectAllLabel | `string` | `"Select all"` | Label next to the header checkbox. |
| header | `boolean` | `true` | Show the select all row with the count. |
| aria-label | `string` |  | Accessible name for the group. |

## When to use

- Picking several items from a short list: repositories, environments, channels
- Permission and notification settings where select all saves clicks
- When a count of selected rows helps, it sits in the header

## When not to use

- Long lists that need search or paging, use a table with a selection column
- Choosing exactly one item, use a radio group
- Independent on and off settings, use switches

## Notes for agents

- It takes a function (onValueChange), so the page or demo that renders it must be a client component
- Uncontrolled by default; pass value plus onValueChange to control it. Ids must be unique and stable
- Select all skips disabled rows and leaves their checked state as it is
- The checked styles are set on the Checkbox from this file, so it does not depend on the primitive's data-checked variant

Docs: https://ui.goodtabs.co/components/checkbox-list