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
size 'sm' | 'md' | 'lg' 'md' Size variant of the checkbox
onCheckedChange (checked: boolean) => void - Callback fired when the checkbox state changes
disabled boolean false Whether the checkbox is disabled
accessibilityLabel string - Accessibility label for screen readers
testID string - Test ID for testing

Variants

Sizes

Three size options for different contexts.

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

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: Renders a Pressable with role="checkbox"; announced as a checkbox by VoiceOver and TalkBack.
  • Label: Pass accessibilityLabel so screen-reader users know what the checkbox controls. Required when no visible label is rendered alongside.
  • Disabled State: accessibilityState.disabled is set so assistive technology announces the disabled state.
  • 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