# Checkbox

Turns an independent option on or off; the choice is saved with the form.

```tsx
import { Checkbox } from "@/components/ui/checkbox"
import { Label } from "@/components/ui/label"

<div className="flex items-center gap-2">
  <Checkbox id="summary" defaultChecked />
  <Label htmlFor="summary">Send me a weekly summary</Label>
</div>
```

## Usage

### What you provide
- `id` + `Label htmlFor`; `checked` / `onCheckedChange` (controlled) or `defaultChecked`.
- For an immediate effect (no Save button), use `Switch`.
- Checkbox lists: `grid gap-3`; label to the right of the control with `gap-2`.

## Accessibility

- For independent choices; when only one option of a group can be chosen, use radio buttons.
- The label is associated and clickable, so it is part of the touch target. Hover, checked, unchecked, mixed and disabled states are distinct.
- `Tab` moves to each checkbox and `Space` toggles it. Disabled checkboxes do nothing.
- Screen readers hear the label, the role and the state (checked, unchecked or mixed). For a mixed parent, set `checked="indeterminate"` and document the toggle order.
- Group related checkboxes in a `<fieldset>` with a `<legend>` that names the group.

_Adapted from Magoo 1.6.0 by Marcelo Sales: [Checkbox](https://magoo.cc/en/components/forms/checkbox.html) (`checkbox`). Magoo is educational guidance; test the behavior in your implementation._

## API

Install:

```bash
npx @aline-aroucha/pui add checkbox
```

```tsx
<Checkbox />
<Label />
```

### Checkbox

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean \| "indeterminate"` | — | Controlled state; `"indeterminate"` shows the mixed state. |
| `defaultChecked` | `boolean \| "indeterminate"` | `false` | Initial state when uncontrolled. |
| `onCheckedChange` | `(checked: boolean \| "indeterminate") => void` | — | Runs when the state changes. |
| `disabled` | `boolean` | `false` | Blocks changes. |
| `required` | `boolean` | `false` | Must be checked to submit. |
| `name` | `string` | — | Form field name. |
| `value` | `string` | `"on"` | Value sent with the form. |

## Related pages

- [Switch](https://aline-aroucha.github.io/pui/components/switch.html)
- [Label](https://aline-aroucha.github.io/pui/components/label.html)
- [Field](https://aline-aroucha.github.io/pui/components/field.html)

---
PUI documentation · https://aline-aroucha.github.io/pui/components/checkbox.html