Checkbox

Usage

Overview

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 CheckboxCards) adds description space when operators must understand a consequence before toggling.

Only show calls I took

When to use

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.

When not to use

Mutually exclusive choices—use Radio or RadioCards.
Single-setting binary toggles with immediate effect and a clear verb-based label—use Switch.
Each option needs descriptive copy to explain consequences—use CheckboxCards.

Content guidelines

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.

Behavior and states

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.

Best practices

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 Dialog 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.

Accessibility

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.

Chat Scroll / Accessibility

Checkbox / API and Development

On this page

Checkbox

Usage

Overview

Only show calls I took

When to use

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.

When not to use

Mutually exclusive choices—use Radio or RadioCards.
Single-setting binary toggles with immediate effect and a clear verb-based label—use Switch.
Each option needs descriptive copy to explain consequences—use CheckboxCards.

Content guidelines

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.

Behavior and states

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.

Best practices

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 Dialog 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.

Accessibility

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.

Chat Scroll / Accessibility

Checkbox / API and Development

On this page