# Checkbox

A control that allows the user to toggle between checked and not checked.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<ComponentPreview name="checkbox" title="checkbox.tsx">
<CheckboxDemo />
</ComponentPreview>

Checkbox is a native button styled with Frakment tokens. It supports checked, unchecked, and indeterminate states, and integrates with `Label` for accessible click-through.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add checkbox
```
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the following dependencies:
</Step>

```bash
npm install lucide-react
```

<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="checkbox" title="components/ui/checkbox.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx title="checkbox.tsx"
import { Checkbox } from "@/components/ui/checkbox";
<DocsBaseSwitcher base="web" component="checkbox" className="mb-6" />
```

```tsx
<Checkbox defaultChecked />
```

## Examples [#examples]

### States [#states]

Pass `checked="indeterminate"` for a partial-selection state.

<ComponentPreview name="checkbox-states" title="checkbox-states.tsx" src="examples/checkbox-states.tsx">
<CheckboxStates />
</ComponentPreview>

```tsx
<Checkbox aria-label="Unchecked" />
<Checkbox aria-label="Checked" defaultChecked />
<Checkbox aria-label="Indeterminate" checked="indeterminate" />
```

### Disabled [#disabled]

<ComponentPreview name="checkbox-disabled" title="checkbox-disabled.tsx" src="examples/checkbox-disabled.tsx">
<CheckboxDisabled />
</ComponentPreview>

```tsx
<Checkbox id="c-dis" disabled />
<Label htmlFor="c-dis">Disabled</Label>
```

### With label [#with-label]

Pair with `Label` and matching `id` / `htmlFor` for a click-through row.

<ComponentPreview name="checkbox-with-label" title="checkbox-with-label.tsx" src="examples/checkbox-with-label.tsx">
<CheckboxWithLabel />
</ComponentPreview>

```tsx
<div className="flex items-center gap-2">
  <Checkbox id="c-a" defaultChecked />
  <Label htmlFor="c-a">Email notifications</Label>
</div>
```

## In Context [#in-context]

### Terms acceptance [#terms-acceptance]

<ComponentPreview name="checkbox-terms" title="checkbox-terms.tsx" src="examples/checkbox-terms.tsx">
<CheckboxTerms />
</ComponentPreview>

### Notification preferences [#notification-preferences]

<ComponentPreview name="checkbox-notifications" title="checkbox-notifications.tsx" src="examples/checkbox-notifications.tsx">
<CheckboxNotifications />
</ComponentPreview>

## API Reference [#api-reference]

### Checkbox [#checkbox]

Extends `React.ComponentProps<"button">`.

<PropsTable rows={[{"name":"checked","type":"boolean | \"indeterminate\"","description":"Controlled state. Use \"indeterminate\" for partial selection."},{"name":"defaultChecked","type":"boolean | \"indeterminate\"","default":"false","description":"Uncontrolled initial state."},{"name":"onCheckedChange","type":"(checked: boolean | \"indeterminate\") => void","description":"Fires when the checkbox toggles."},{"name":"disabled","type":"boolean","default":"false","description":"Removes the checkbox from the tab order."},{"name":"required","type":"boolean","default":"false","description":"Native form requirement."}]} />

## Controlled [#controlled]

```tsx
const [checked, setChecked] = React.useState(false)
<Checkbox checked={checked} onCheckedChange={setChecked} />
```

## States [#states-1]

| State | How |
| :-- | :-- |
| Unchecked | default |
| Checked | `checked` prop |
| Indeterminate | `checked="indeterminate"` |
| Disabled | `disabled` prop |

## Data Attributes [#data-attributes]

| Attribute | Values |
| :-- | :-- |
| `data-slot` | `checkbox` |
| `data-state` | `checked` \| `unchecked` \| `indeterminate` |
| `data-disabled` | `true` |

## Accessibility [#accessibility]

- `Checkbox` renders a button with `role="checkbox"` and manages `aria-checked`. Do not add `role` manually.
- Always pair with a `label` or `FieldLabel` using `htmlFor`. Clicking the label toggles the checkbox.
- The indeterminate state is set via `checked="indeterminate"`. It has no user-triggered equivalent; set it when some but not all children are selected.
- `disabled` removes the checkbox from the tab order. If the value is informational, use `readOnly` instead of `disabled`.

## Best Practices [#best-practices]

- **One checkbox per independent option.** Do not use it for exclusive choices — use `RadioGroup`.
- **Labels go to the right.** `Checkbox` then `label` is the standard pattern.
- **Instant toggle.** Checkboxes toggle immediately; there is no separate save step.
- **Indeterminate is a display state.** Set it programmatically when a parent has mixed child states.
- **Use `Switch` for immediate settings.** Checkbox reads as "queued until save" to many users.

## Related Components [#related-components]

- [Radio Group](/docs/components/radio-group) — single choice
- [Switch](/docs/components/switch) — on/off toggle
- [Field](/docs/components/field) — label + description

## Anatomy [#anatomy]

<ComponentPreview name="checkbox-anatomy" title="checkbox-anatomy.tsx" src="examples/checkbox-anatomy.tsx">
<CheckboxAnatomy />
</ComponentPreview>

- **Box** — 16px square with a 1px border, `bg-primary` when checked
- **Indicator** — checkmark icon, rendered only when checked
- **Label** — separate element, linked with `htmlFor`