Checkbox captures independent multi-select decisions: permissions, feature flags, filter facets, "which columns to show" pickers. Each checkbox answers its own yes/no question, independent of its peers. The mental model is "turn each of these on or off"—different from a radio group, where the choices compete, and from a switch, which conveys an immediate setting change. Plain checkboxes suit dense settings and filter panels; the card variant (see CheckboxCardGroup) adds description space when operators must understand a consequence before toggling.
- Independent options where any subset may be selected (agency permissions, filter facets, column visibility).
- Settings tables and side panels where vertical space is limited and the label is enough.
- Parent/child lists that need an indeterminate state on the group header.
- Mutually exclusive choices—use
Radio or RadioCardGroup.
- Single-setting binary toggles with immediate effect and a clear verb-based label—use
Switch.
- Each option needs descriptive copy to explain consequences—use
CheckboxCardGroup.
- Parallel, positive phrasing ("Enable transcript export", "Enable call recording"). Mixing positives with negated sentences ("Disable auto-acknowledgment") wrecks scannability.
- Helper text explains the consequence, not just the label. "Enable transcript export – Exports the last 24 hours automatically" tells the operator what will happen.
- Localize every string with
formatMessage.
- Controlled vs. uncontrolled. Controlled when syncing to form state or remote data; uncontrolled for self-contained UI toggles.
- Indeterminate. Reflect partial child selection on a group header; clear state is a checked, unchecked, or indeterminate checkbox—not a third check-like visual.
- Disabled. Explain the reason when operators commonly ask why (permission dependency, another flag gating the option). Disabled without rationale is a support ticket in waiting.
Do
- Group related options with consistent spacing; align labels for top-to-bottom scanning.
- Show validation at the group level and surface summaries on submit when the group drives a form.
- Include the full label text in the click target so operators hit the label to toggle.
Don't
- Hide risky toggles without confirmation when a mistake affects production traffic. Pair with a
Modal confirmation step.
- Use cards when a one-line label suffices. Cards add height without adding clarity for small yes/no questions.
- Mix checkboxes with radios in the same visual group without clear separation—the mental models collide.
Each checkbox has an associated label, a keyboard-operable toggle, and an indeterminate state that's exposed to assistive technology. See Accessibility for the full contract.
- Checkbox cards for rich multi-select with per-option description.
- Switch for binary settings with immediate effect.
- Radio for mutually exclusive selection.
- Label for form label standards.
