Checkbox

A flexible checkbox component built on React Aria's Checkbox component with support for individual checkboxes and checkbox groups. Features indeterminate state, custom styling, and full accessibility support.

Checkbox Props

Prop	Type	Default	Description
`children`	`ReactNode`	-	Required - Label text or content displayed next to the checkbox
`isSelected`	`boolean`	`false`	Whether the checkbox is checked (controlled)
`defaultSelected`	`boolean`	`false`	Initial checked state (uncontrolled)
`isIndeterminate`	`boolean`	`false`	Whether to show indeterminate state (mixed/partial selection)
`onChange`	`(isSelected: boolean) => void`	-	Called when checkbox state changes
`isDisabled`	`boolean`	`false`	Whether the checkbox is disabled
`isReadOnly`	`boolean`	`false`	Whether the checkbox is read-only
`isRequired`	`boolean`	`false`	Whether the checkbox is required
`value`	`string`	-	Value used when checkbox is part of a group
`className`	`string`	-	Additional CSS classes for the checkbox container

Extends all React Aria CheckboxProps.

CheckboxGroup Props

Prop	Type	Default	Description
`options`	`{ label: string; value: string }[]`	-	Required - Array of checkbox options
`value`	`string[]`	-	Array of selected values (controlled)
`defaultValue`	`string[]`	-	Initial selected values (uncontrolled)
`onChange`	`(value: string[]) => void`	-	Called when selection changes
`isDisabled`	`boolean`	`false`	Whether all checkboxes are disabled
`isReadOnly`	`boolean`	`false`	Whether all checkboxes are read-only
`isRequired`	`boolean`	`false`	Whether at least one checkbox must be selected

Extends all React Aria CheckboxGroupProps.

Usage Examples

Basic Checkbox

tsx

<Checkbox>Accept terms and conditions</Checkbox>

Default Selected

tsx

<Checkbox defaultSelected={true}>Remember me</Checkbox>

Disabled State

tsx

<Checkbox isDisabled>This option is not available</Checkbox>

CheckboxGroup

tsx

<CheckboxGroup
  options={[
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Orange', value: 'orange' },
  ]}
/>

Select All Pattern

tsx

function SelectAll() {
  const allOptions = [
    { label: 'Feature A', value: 'a' },
    { label: 'Feature B', value: 'b' },
    { label: 'Feature C', value: 'c' },
  ];

  const [selectedFeatures, setSelectedFeatures] = useState(['a']);

  const allSelected = selectedFeatures.length === allOptions.length;
  const someSelected = selectedFeatures.length > 0 && !allSelected;

  const handleSelectAll = (checked: boolean) => {
    if (checked) {
      setSelectedFeatures(allOptions.map(opt => opt.value));
    } else {
      setSelectedFeatures([]);
    }
  };

  return (
    <div>
      <Checkbox isSelected={allSelected} isIndeterminate={someSelected} onChange={handleSelectAll}>
        Select All Features
      </Checkbox>

      <hr className="my-2" />

      <CheckboxGroup value={selectedFeatures} onChange={setSelectedFeatures} options={allOptions} />
    </div>
  );
}

Styling

CSS Variables

The component uses the following CSS variables for theming:

--color-font: Checkbox text color
--hl-sm: Standard border color
--hl-xs: Highlight for hover/selected/indeterminate
--color-success: Checkmark color

You can customize these variables in your CSS to theme the checkbox appearance.

Checkbox vs Switch

Use Checkbox When	Use Switch When
Multiple selections allowed	Single on/off toggle
Form with multiple options	Settings that apply immediately
Selection doesn't take effect immediately	Action happens instantly
Need indeterminate state	Need instant feedback
Example: Select features to enable	Example: Enable dark mode