A box for a binary choice — on its own, or one of several independently-selectable options in a group. Its value is submitted with a form; when a setting applies immediately instead, use a toggle.
Real DOM drivers set every state; demo classes force hover and focus here. One size — size.icon.md. Unchecked hover previews the primary check on the unfilled box; selection reverses it onto the primary fill, which remains filled as it steps to its hover color.
| Example | State | Driver | Roles | Usage |
|---|---|---|---|---|
| Rest, unchecked | — | border.strongsurface.page | An empty box, ready to check | |
| Hover | :hover | surface.pageaction.primary.bg | The primary check previews selection on the unfilled box | |
| Checked | :checked | action.primary.bg.text | A check mark on the primary fill | |
| Checked + hover | :checked:hover | action.primary.hover.text | The fill responds without disguising the selected value | |
| Indeterminate | :indeterminate | action.primary.bg.text | A dash — some but not all in a group are checked; set via el.indeterminate, not an attribute | |
| Focus | :focus-visible | focus.ring | Keyboard focus — the shared ring | |
| Invalid | [aria-invalid] | status.error.border | Pair with an error message via aria-describedby | |
| Disabled | :disabled | action.disabled.bgborder.default | Excluded from interaction and the tab order |
The native fieldset.ds-choice-group supplies the rounded boundary, inset, legend, and owned help line; Checkbox keeps its square semantics. The "select all" parent reflects its children and loads indeterminate here.
Checkboxes select independently — each answers its own yes/no.
| Verdict | Rule |
|---|---|
| Do | Give every checkbox a label — a visible one via its row, or aria-label when the surrounding text is the label. |
| Do | Group visibly bounded related choices in fieldset.ds-choice-group under a real legend; each checkbox still toggles on its own. |
| Do | Set aria-invalid with a message referenced by aria-describedby — never color alone. |
| Don’t | Reach for a checkbox for mutually exclusive options — that is Radio — or for a setting that applies at once — that is Toggle. |