# Checkbox

A native checkbox drawn by the theme, with an indeterminate (mixed) state.

```ehtml Example
import { Checkbox, CheckboxGroup } from "@elements/ui/checkbox";
import { Label } from "@elements/ui/label";

<Label><Checkbox checked={form.terms} /> Accept terms and conditions</Label>

// Select all: checked when every row is, mixed when only some are.
<Checkbox checked={rows.every((r) => r.on)}
          indeterminate={rows.some((r) => r.on) && !rows.every((r) => r.on)}
          onCheckedChange={(on) => rows.forEach((r) => r.on = on)}
          attrs={{ "aria-label": "Select all" }} />
```

## Parts

| Part | What it is |
|---|---|
| `.checkbox` | The wrapper: the input and the indicator stacked in one cell. |
| `.checkbox-input` | The native `<input type="checkbox">`. |
| `.checkbox-indicator` | The check or the dash; ignores the pointer. |
| `.checkbox-group` | CheckboxGroup's role="group" column; name it with aria-labelledby in attrs. |

## Attributes

### Checkbox

| Attribute | Type | Default | Description |
|---|---|---|---|
| `checked` | `boolean` (two-way) | `false` | Bind it to state; a click writes back. |
| `indeterminate` | `boolean` (two-way) | `false` | The mixed state. A click clears it and checks the box. |
| `value` | `string` | `"on"` | Submitted with name while checked. |
| `name` | `string` | `""` | Form field name. |
| `uncheckedValue` | `string \| undefined` | `undefined` | Submitted under name while unchecked. By default an unchecked box submits nothing. |
| `disabled` | `boolean` | `false` | Native disabled. |
| `readOnly` | `boolean` | `false` | Focusable and announced, but a click, Space or a label press does not change it. |
| `required` | `boolean` | `false` | The form will not submit until it is checked. |
| `invalid` | `boolean` | `false` | aria-invalid and the danger border. |
| `parent` | `boolean` | `false` | Inside a CheckboxGroup: checked when every child is, mixed when some are. A press checks all, then clears all, then brings back the last mix. |
| `class` | `string` | `""` | Extra classes on the wrapper. |
| `attrs` | `Record<string, string \| number \| boolean \| undefined>` | `{}` | Attributes for the `<input>`: id, aria-label, aria-describedby, data-\*. |
| `onCheckedChange` | `(checked: boolean, details: ChangeDetails) => void` | `() => {}` | The user changed it, or a form reset restored it (not called for changes made in code). It runs before the change with details second (reason, event, cancel(), isCanceled); details.cancel() keeps the state. |

### CheckboxGroup

| Attribute | Type | Default | Description |
|---|---|---|---|
| `value` | `string[]` (two-way) | `[]` | The values of the checked boxes inside the group. Bind it to state; a press writes back. |
| `allValues` | `string[]` | `[]` | Every child value the parent box governs. Empty means every child in the group. |
| `disabled` | `boolean` | `false` | Disables every checkbox in the group. |
| `onValueChange` | `(value: string[], details: ChangeDetails) => void` | `() => {}` | The user changed the set, or a form reset restored it. details.cancel() keeps it. |

## Keyboard

| Keys | Action |
|---|---|
| `Space` | Toggles the checkbox. From the mixed state it becomes checked. |
| `Enter` | Does nothing: it neither toggles the box nor submits the form. |
| `Tab` | Moves to the next control. |

## Data attributes

| Attribute | Values | On | Description |
|---|---|---|---|
| `data-state` | `"checked" \| "unchecked" \| "indeterminate"` | wrapper, input, indicator |  |
| `data-checked, data-unchecked, data-indeterminate` | present for the current state | wrapper, input, indicator | The same state as data-state, one attribute per value. |
| `data-disabled` | present while disabled | wrapper, indicator |  |
| `data-invalid` | present while invalid | input |  |
| `data-readonly` | present while readOnly | wrapper, input, indicator |  |
| `data-required` | present while required | wrapper, indicator |  |
| `data-parent` | present on a parent box | input |  |
| `data-disabled` | present while the group is disabled | CheckboxGroup |  |

## Accessibility

- A native checkbox: its role, checked and mixed states are the browser's (the mixed state is announced from the indeterminate property).
- Name it with a wrapping `<Label>`, `<Label htmlFor>`, aria-label in attrs, or a `<Field>`.
- A group of related checkboxes goes in an element with role="group" and aria-labelledby, or a `<FieldSet>` with a legend.
- A CheckboxGroup parent box points aria-controls at its children.
- Focus shows the theme ring as a box-shadow; no state changes its size.

## See also

- [Label](label): A native label for a control, which dims when the control is disabled.
- [ButtonGroup](button-group): Related buttons, or an input and its buttons, joined into one control.
- [Input](input): A native text input in the theme's control chrome, with a two-way value.
- [InputGroup](input-group): An Input or Textarea with icons, text and buttons inside one box.
- [Textarea](textarea): A native multi-line input that grows with its content, between rows and maxRows.
- [Field](field): A label, a control, a description and an error wired together, with native validation that never moves the layout.