Checkboxes provide users with a range of options for a given statement where the user may select any number of choices, including zero, one or multiple. In a form, always place checkboxes underneath each other to aid in a user’s ability to scan the form.

Usage

The Checkbox component maps to a checkbox input and a label. The label is provided as children to the component. If you need custom label behaviour use the CheckboxPrimitive component.

Edit in Playroom

<Stack gap="medium">
  <Checkbox checked={false}>Unchecked</Checkbox>
  <Checkbox checked>Checked</Checkbox>
  <Checkbox checked="mixed">Indeterminate</Checkbox>
  <Checkbox disabled>Disabled</Checkbox>
  <Checkbox checked disabled>
    Checked + disabled
  </Checkbox>
</Stack>

Controlled

The Checkbox component passes on the original event through the onChange handler. Use the event target's checked property to get the latest value and update state accordingly.

Edit in Playroom

const [checked, setChecked] = useState(false);
const handleChange = (event) => setChecked(event.target.checked);
return (
  <Checkbox checked={checked} onChange={handleChange}>
    Controlled
  </Checkbox>
);

Size

The Checkbox is available in a "small" size. Reserve this appearance for data-rich, dense interfaces.

Edit in Playroom

<Stack gap="small">
  <Checkbox size="small" checked={false}>
    Unchecked
  </Checkbox>
  <Checkbox size="small" checked>
    Checked
  </Checkbox>
  <Checkbox size="small" checked="mixed">
    Indeterminate
  </Checkbox>
  <Checkbox size="small" disabled>
    Disabled
  </Checkbox>
  <Checkbox size="small" checked disabled>
    Checked + disabled
  </Checkbox>
</Stack>

Guidelines

Avoid checkboxes with actions that are the opposite of what the user expects.
The default view for checkboxes has no option selected.
Checkbox options should be listed in a logical order (alphabetical, numerical, time-based, etc).

Groups

Use the CheckboxGroup to implement a group of checkboxes. Each Checkbox within a group must have a "value" prop.

Edit in Playroom

const [selected, setSelected] = useState(['bulbasaur']);
return (
  <CheckboxGroup value={selected} onChange={setSelected}>
    <Stack gap="medium">
      <Checkbox value="bulbasaur">Bulbasaur</Checkbox>
      <Checkbox value="charmander">Charmander</Checkbox>
      <Checkbox value="squirtle">Squirtle</Checkbox>
    </Stack>
  </CheckboxGroup>
);

Primitive

Use the CheckboxPrimitive to implement custom behaviours and appearances.

Edit in Playroom

const [checked, setChecked] = useState(false);
return (
  <Inline
    as="label"
    padding="large"
    borderRadius="medium"
    background={checked ? 'active' : 'muted'}
    gap="medium"
  >
    <CheckboxPrimitive
      checked={checked}
      onChange={(e) => setChecked(e.target.checked)}
    />
    <Text>Custom label implementation</Text>
  </Inline>
);

Indeterminate state

The indeterminate state of a checkbox input element is controlled by JavaScript, not HTML attribution. To make things more declarative and less confusing Balance checkboxes accept a "tri-state"; the checked value for a checkbox may be true | false | 'mixed', where "mixed" indicates an indeterminate state aligning with the aria-checked attribute.