Checkbox
Last Updated: September 2026Checkboxes capture binary or multi-select choices in forms, including indeterminate parent states.
Source CodeAnatomy
link- 1Control
- 2Label
- 3Indicator
Variants
linkDefault
Unchecked until the user selects it.
Checked
defaultChecked or controlled checked for a pre-selected state.
Indeterminate
Partial selection — common for parent/child multi-select. Visually overrides checked.
Disabled
Non-interactive while a prerequisite is unmet.
Without label
Control-only — pair with an external label via aria-label or htmlFor.
Usage Guidelines
linkWhen to use
- •For binary choices in forms (agree, enable, select a row).
- •When the label should sit beside a clear checked/unchecked affordance.
- •For multi-select lists where each option is independent.
When not to use
- •For on/off settings with a track affordance — use Switch.
- •For mutually exclusive options — use Select or Segmented Control.
- •For actions that submit or navigate — use Button.
Use concise labels that describe the consequence of checking.
Don't use vague labels like “Yes” without stating what is being accepted.
Use indeterminate on a parent when only some children are selected.
Don't use Switch for form agreement or multi-select — use Checkbox.
Behaviors
linkValue model
- •Uncontrolled: defaultChecked.
- •Controlled: checked + onCheckedChange.
- •indeterminate takes visual precedence over checked while active.
Label wrapping
- •When label is set, the control and Typography label share one clickable <label> row.
- •className applies to the wrapper when labeled; to the control when label is omitted.
Disabled
- •disabled blocks interaction and uses the disabled palette over hover styles.
- •Works with checked and indeterminate states.
Content Guidelines
linkLabels
- •Prefer affirmative, outcome-focused phrasing (“Send reminders”).
- •Keep labels short enough to scan in a vertical list.
Indeterminate
- •Reserve indeterminate for partial group selection — not as a third permanent value.
- •Clear indeterminate when the user toggles the parent to fully on or off.
Accessibility
linkText & Labels
- •Prefer the label prop so the whole row is activatable.
- •Without label, provide aria-label or associate an external <label>.
ARIA attributes
- •Built on Base UI Checkbox — exposes checked and mixed (indeterminate) states.
- •Disabled checkboxes are not operable and announce as disabled.
Keyboard Support
- •Tab → focus the control.
- •Space → toggle checked.
- •Indeterminate is cleared to checked on activation (Base UI behavior).
WCAG Compliance Standards
FAQs
linkCheckbox vs Switch?
Checkbox for form choices and multi-select; Switch for immediate on/off settings with a track affordance.
How does indeterminate work?
Pass indeterminate — it visually overrides checked. Use it for “select all” parents when only some children are selected.
Controlled vs uncontrolled?
Use checked + onCheckedChange when you own state; defaultChecked when you don’t need to.