# Checkbox

```tsx
import { Checkbox } from '@tangible/ui';
```

Interactive docs and examples: [Checkbox in Storybook](https://storybook-tangible-ui.pages.dev/?path=/docs/forms-checkbox--docs).

## Checkbox props

| Prop | Type | Default | Description |
| - | - | - | - |
| `checked?` | `boolean` | | |
| `className?` | `string` | | |
| `defaultChecked?` | `boolean` | `false` | |
| `disabled?` | `boolean` | | |
| `indeterminate?` | `boolean` | `false` | |
| `label?` | `ReactNode` | | When provided, renders the checkbox inside a `<label>` with this content. When omitted, renders a bare `<input>` — you must provide an accessible name via `aria-label`, `aria-labelledby`, or a wrapping `Field.Control` + `Field.Label`. |
| `onCheckedChange?` | `(checked: boolean) => void` | | |

Also accepts the standard attributes of `InputHTMLAttributes` (`data-*`, `aria-*`, event handlers), passed to the element it renders.

## Examples

- [Basic](https://storybook-tangible-ui.pages.dev/?path=/story/forms-checkbox--basic): Default unchecked state with visible label.

- [Bare](https://storybook-tangible-ui.pages.dev/?path=/story/forms-checkbox--bare): Bare checkbox with no visible label — requires `aria-label` for accessibility.

- [Checked](https://storybook-tangible-ui.pages.dev/?path=/story/forms-checkbox--checked): Checked by default using `defaultChecked`.

- [Indeterminate](https://storybook-tangible-ui.pages.dev/?path=/story/forms-checkbox--indeterminate): Indeterminate state — commonly used as a "select all" parent in a checkbox group.

- [Controlled](https://storybook-tangible-ui.pages.dev/?path=/story/forms-checkbox--controlled): Controlled checkbox — parent owns the checked state.

- [Indeterminate Toggle](https://storybook-tangible-ui.pages.dev/?path=/story/forms-checkbox--indeterminate-toggle): Select-all pattern with indeterminate parent. Uses `<fieldset>`/`<legend>` for grouping.

- [With Field](https://storybook-tangible-ui.pages.dev/?path=/story/forms-checkbox--with-field): Checkbox inside a Field — the `label` prop handles the visible inline label.
  Skip `Field.Label` (checkbox is self-labelling). `Field.Control` still injects
  `aria-describedby` (helper/error) and `aria-invalid` — the name wiring is the
  only part that doesn't apply.

- [With Field Error](https://storybook-tangible-ui.pages.dev/?path=/story/forms-checkbox--with-field-error): Error state — `Field.Control` injects `aria-invalid="true"` and
  `aria-describedby` pointing to the error. The `label` prop provides the
  visible inline label. No `Field.Label` needed.

- [Multiple Options](https://storybook-tangible-ui.pages.dev/?path=/story/forms-checkbox--multiple-options): Multiple related checkboxes grouped with `<fieldset>`/`<legend>`.

Other stories: Disabled, Disabled Checked ([interactive page](https://storybook-tangible-ui.pages.dev/?path=/docs/forms-checkbox--docs)).

## Component API tokens

Read via fallback, never declared. Set one on an ancestor to restyle every instance under it.

- `--tui-checkbox-accent`
- `--tui-checkbox-border`
- `--tui-checkbox-border-hover`
- `--tui-checkbox-border-invalid`
- `--tui-checkbox-radius`
- `--tui-checkbox-bg`
- `--tui-checkbox-size`
- `--tui-checkbox-gap`
- `--tui-checkbox-label-color`

---

Interactive version: https://storybook-tangible-ui.pages.dev/?path=/docs/forms-checkbox--docs