Skip to main content
A checkbox component that allows users to select one or more options.

​
Import

import { Checkbox } from '@base-ui/react/checkbox';

​
Anatomy

The Checkbox component consists of two parts:
  • Checkbox.Root - The checkbox control itself
  • Checkbox.Indicator - Visual indicator for the checked state

​
Basic Usage

<Checkbox.Root>
  <Checkbox.Indicator />
</Checkbox.Root>

​
Key Features

  • Controlled and uncontrolled modes
  • Indeterminate state support
  • Accessible with proper ARIA attributes
  • Works seamlessly with Field and Form components
  • Support for parent-child checkbox relationships
  • Custom render props

​
Key Props

​
checked

Type: boolean Default: undefined Whether the checkbox is currently ticked. Use with onCheckedChange for controlled mode. 
const [checked, setChecked] = React.useState(false);

<Checkbox.Root checked={checked} onCheckedChange={setChecked}>
  <Checkbox.Indicator />
</Checkbox.Root>

​
defaultChecked

Type: boolean Default: false Whether the checkbox is initially ticked. Use for uncontrolled mode. 
<Checkbox.Root defaultChecked>
  <Checkbox.Indicator />
</Checkbox.Root>

​
onCheckedChange

Type: (checked: boolean, eventDetails: ChangeEventDetails) => void Event handler called when the checkbox is ticked or unticked.

​
disabled

Type: boolean Default: false Whether the component should ignore user interaction.

​
readOnly

Type: boolean Default: false Whether the user should be unable to tick or untick the checkbox.

​
required

Type: boolean Default: false Whether the user must tick the checkbox before submitting a form.

​
indeterminate

Type: boolean Default: false Whether the checkbox is in a mixed state: neither ticked, nor unticked. 
<Checkbox.Root indeterminate>
  <Checkbox.Indicator />
</Checkbox.Root>

​
name

Type: string Identifies the field when a form is submitted.

​
value

Type: string The value of the selected checkbox.

​
Styling

<Checkbox.Root className="w-5 h-5 border-2 border-gray-300 rounded flex items-center justify-center data-[checked]:bg-blue-500 data-[checked]:border-blue-500">
  <Checkbox.Indicator className="text-white">
    <svg width="12" height="12" viewBox="0 0 12 12" fill="currentColor">
      <path d="M10 3L4.5 8.5L2 6" stroke="currentColor" strokeWidth="2" fill="none" />
    </svg>
  </Checkbox.Indicator>
</Checkbox.Root>

​
Common Patterns

​
With Label

import { Field } from '@base-ui/react/checkbox';

<Field.Root>
  <div className="flex items-center gap-2">
    <Checkbox.Root name="terms">
      <Checkbox.Indicator />
    </Checkbox.Root>
    <Field.Label>I accept the terms and conditions</Field.Label>
  </div>
</Field.Root>

​
Indeterminate State

function ParentCheckbox() {
  const [checked, setChecked] = React.useState([false, false]);
  const allChecked = checked.every(Boolean);
  const indeterminate = checked.some(Boolean) && !allChecked;

  return (
    <div>
      <Checkbox.Root
        checked={allChecked}
        indeterminate={indeterminate}
        onCheckedChange={(c) => setChecked([c, c])}
      >
        <Checkbox.Indicator />
      </Checkbox.Root>
      {checked.map((c, i) => (
        <Checkbox.Root
          key={i}
          checked={c}
          onCheckedChange={(val) => {
            const newChecked = [...checked];
            newChecked[i] = val;
            setChecked(newChecked);
          }}
        >
          <Checkbox.Indicator />
        </Checkbox.Root>
      ))}
    </div>
  );
}