Checkbox

Accessible checkbox with label, indeterminate, and size variants.

Status: stable. Group: form. Markdown version: /design-system/components/checkbox.md

When to use

Checkbox is a labelled native input for an independent yes/no choice that takes effect when the form is submitted. It supports controlled and uncontrolled use, an indeterminate state for select-all parents, and carries its own error and helper text.

When not to use

Do not rely on the native indeterminate HTML attribute; there is no such serialised attribute. Use the prop (set as a DOM property).
Do not use a Checkbox for an immediate on/off effect; that is Switch.

Look-alikes

Badge: Do not use Badge as an interactive action or toggle; use Button for actions and Switch or Checkbox for state.
Button: Do not use Button for an on/off state; use Switch. For multi-select within a group, use Checkbox or CheckboxGroup.
Radio: Do not render a lone radio; a choice with one option is a Checkbox.
RadioGroup: Use RadioGroup when the user picks exactly one option from an exclusive set; Checkbox is an independent yes or no choice.
Switch: Do not use a Checkbox for an immediate on/off effect; that is Switch.

Props

Checkbox props
Prop	Type	Default	Description	Required
`label`	`string`	none	Label text displayed next to the checkbox.	No
`showLabel`	`boolean`	`true`	Whether to show the label text.	No
`checked`	`boolean`	none	Checked state (controlled).	No
`indeterminate`	`boolean`	`false`	Indeterminate (mixed) state.	No
`disabled`	`boolean`	`false`	Disables interaction and dims the control.	No
`defaultChecked`	`boolean`	none	Initial checked state for uncontrolled use.	No
`size`	`"sm" \| "md" \| "lg"`	`md`	Size.	No
`onCheckedChange`	`(checked: boolean) => void`	none	Called with the next checked value when toggled.	No
`id`	`string`	none	Custom ID for the checkbox element; auto-generated when omitted.	No
`error`	`string`	none	Error message under the control; sets aria-invalid and aria-describedby.	No
`helperText`	`string`	none	Supporting text under the control; always rendered, below `error` when both are set.	No

Variants

Available sizes: sm, md, lg (default md).

Invalid combinations

MUST NOT: checked and defaultChecked set together. checked makes the component controlled and defaultChecked uncontrolled; pass one, not both.

Keyboard

Checkbox keyboard behaviour
Key	Behaviour
Space	Activates or toggles the focused control. (standard)

Rows marked (standard) name a key the contract lists without a description; the behaviour shown is the usual one for that key.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

Checkbox rules
Level	Rule	How it is checked
MUST NOT	`checked` and `defaultChecked` set together. `checked` makes the component controlled and `defaultChecked` uncontrolled; pass one, not both.	Checked by the MCP tool validate_component_usage.
MUST	ARIA: Associated label.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Indeterminate exposes aria-checked mixed when applicable.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	Required stories produce no axe violations at the configured severity.	Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8.
MUST	The accessibility tree (role, name, state) matches the committed snapshot for every required story.	Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2.
MUST	The component remains legible and operable under a real browser forced-colors: active pass.	Automated by `npm run test:stories:hc`.
MUST	Every documented keyboard interaction works as specified.	Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2.
MUST	A human completed an end-to-end accessibility review of this component.	Manual review, last on 2026-11-04.
SHOULD	Write the label as the positive assertion being agreed to (Subscribe to the newsletter).	Not stated in the contract.
SHOULD	Use indeterminate only on a select-all parent whose children are mixed; activating it resolves to checked.	Not stated in the contract.
SHOULD	Use the error prop for validation such as required consent; it wires aria-invalid and announces via role=alert.	Not stated in the contract.
SHOULD	Group related checkboxes with CheckboxGroup or FormField so a legend names the set.	Not stated in the contract.
SHOULD NOT	Do not hide the label with showLabel=false unless adjacent visible text names the control; the label is still the accessible name.	Not stated in the contract.

Install and import

Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
Import: import { Checkbox } from "@digitaltableteur/react";
Entry point: @digitaltableteur/react/forms exports it too.
Styles: import @digitaltableteur/react/style.css once at the app boundary.
Also available as the custom element <dt-checkbox>; see the custom elements manifest.