Atom

Checkbox

Form control for selecting one or more options from a set, with support for indeterminate state.

Overview

The Checkbox component is a form control that allows users to select one or more options from a set. It supports a third "indeterminate" state useful for parent checkboxes that represent partial selection of child items.

Props

Prop Type Default Description
checked boolean false Whether the checkbox is checked
indeterminate boolean false Whether the checkbox is in indeterminate state
onCheckedChange (checked: boolean) => void - Callback fired when the checkbox state changes
size 'sm' | 'md' | 'lg' 'md' Size variant of the checkbox
disabled boolean false Whether the checkbox is disabled

Variants

Sizes

Three size options for different contexts.

<Checkbox size="sm" />
<Checkbox size="md" />
<Checkbox size="lg" />

States

Unchecked, checked, and indeterminate states.

Examples

With Label

Typical usage with an associated label.

<label style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
  <Checkbox checked={agreed} onCheckedChange={setAgreed} />
  <span>I agree to the terms and conditions</span>
</label>

Checkbox Group

Multiple checkboxes for selecting several options.

Select features:

Select All Pattern

Parent checkbox with indeterminate state for partial selection.

Accessibility

  • Role: Uses native checkbox input for proper semantics.
  • Keyboard Support: Space key toggles state, Tab navigates.
  • Screen Reader: Announces checked/unchecked/mixed state and role.
  • Indeterminate: Announced as "mixed" state for screen readers.
  • Focus Management: Visible focus ring on keyboard navigation.
  • WCAG Compliance: Meets AA standards.

Best Practices

  • Always pair checkboxes with a visible label
  • Use Checkbox for form fields that require submission
  • Use Switch instead for settings with immediate effect
  • Use Radio buttons for mutually exclusive single selection
  • Use indeterminate state only for parent checkboxes representing partial selection