# Checkbox

> A yes or a no: an option that is on or off, independent of any other.

A checkbox holds a yes or a no: an option that is on or off, independent of any
other.

## When to use

Use a checkbox for a setting that takes effect with the rest of a form, and for
choosing any number of items from a list. For a choice of exactly one among
several, use a [radio group](https://ui.publictheta.com/components/radio-group.md) or a [select](https://ui.publictheta.com/components/select.md). For a setting that
takes effect at once, a switch says so more plainly.

## Best practices

**Label what being checked means.** Phrase the label so that checked is yes:
"Send me updates", not "Don't send updates".

**Make the label part of the target.** A click or tap on the label changes the
checkbox, as one on the box does.

**Show a third state only when it is true.** A checkbox is mixed when it stands
for several things that disagree, or for a value not yet given. Choosing it turns
it on; people cannot return it to mixed themselves.

**Disable rather than hide** a checkbox that does not apply at the moment.

## Platform considerations

**Keyboard.** Space turns the checkbox on and off; Tab moves to and past it.

**Touch.** The box is larger, and a tap near it reaches it: its target is at
least 44 CSS pixels across.

**Assistive technology.** It is a checkbox, named by its label, stating whether
it is checked, unchecked or mixed.

## Behaviour

Each statement is verified by a test in Chromium, Chromium (touch), Firefox, WebKit, WebKit (touch), unless it names the environments it applies to or is marked open.

### Semantics

- Is a checkbox named by its label, saying whether it is checked.
- Neither on nor off is stated as mixed.
- Has no accessibility violations in any state.

### Changing

- A click turns it on, and another turns it off.
- A click on its label does the same.
- Space turns it on and off.
- From mixed, a click turns it on.
- When disabled it cannot be changed.

### Touch

- Under a finger, a tap 20 pixels from its centre still reaches it. *(Chromium (touch), WebKit (touch))*

## Reference implementation

React: `npx shadcn@latest add https://ui.publictheta.com/r/checkbox.json`