Checkbox

Checkbox is a user interface control that enables users to toggle between checked, unchecked, and indeterminate states.

Anatomy

Import and assemble the component:

1import { Checkbox } from "@raystack/apsara";
2

3<Checkbox />

Use Checkbox.Group to manage shared state across multiple checkboxes:

1<Checkbox.Group defaultValue={["apple"]}>
2  <Checkbox name="apple" />
3  <Checkbox name="banana" />
4  <Checkbox name="cherry" />
5</Checkbox.Group>

Usage

A checkbox on its own, then in a group — where a parent can both reflect and drive the children beneath it.

Size variants

Two sizes. large is the default; small fits table rows and dense lists.

1<Checkbox size="large" />

States

A checkbox can be checked, unchecked, or indeterminate — the third state for a parent whose children are only partly selected.

1<Checkbox />

Controlled

Pass checked with onCheckedChange to own the state — needed when the value lives in a form, gates another control, or has to be read back on submit.

1(function ControlledCheckbox() {
2  const [checked, setChecked] = React.useState(false);
3

4  return (
5    <Flex direction="column" gap={5}>
6      <Flex align="center" gap={3}>
7        <Checkbox checked={checked} onCheckedChange={setChecked} id="terms" />
8        <Label htmlFor="terms">I accept the terms</Label>
9      </Flex>
10      <Button size="small" disabled={!checked}>
11        Continue
12      </Button>
13    </Flex>
14  );
15})

Group

Use Checkbox.Group to coordinate multiple checkboxes with shared state.

1<Checkbox.Group defaultValue={["banana"]}>
2  <Flex direction="column" gap={3}>
3    <Flex gap={3} align="center">
4      <Checkbox name="apple" id="cg-apple" />
5      <label htmlFor="cg-apple">Apple</label>
6    </Flex>
7    <Flex gap={3} align="center">
8      <Checkbox name="banana" id="cg-banana" />
9      <label htmlFor="cg-banana">Banana</label>
10    </Flex>
11    <Flex gap={3} align="center">
12      <Checkbox name="cherry" id="cg-cherry" />
13      <label htmlFor="cg-cherry">Cherry</label>
14    </Flex>
15  </Flex>

Horizontal Group

Use the orientation prop to lay out checkboxes in a horizontal row.

1<Checkbox.Group defaultValue={["banana"]} orientation="horizontal">
2  <Flex gap={3} align="center">
3    <Checkbox name="apple" id="ch-apple" />
4    <label htmlFor="ch-apple">Apple</label>
5  </Flex>
6  <Flex gap={3} align="center">
7    <Checkbox name="banana" id="ch-banana" />
8    <label htmlFor="ch-banana">Banana</label>
9  </Flex>
10  <Flex gap={3} align="center">
11    <Checkbox name="cherry" id="ch-cherry" />
12    <label htmlFor="ch-cherry">Cherry</label>
13  </Flex>
14</Checkbox.Group>

Disabled Group

Disable the entire group to prevent user interaction.

1<Checkbox.Group defaultValue={["apple"]} disabled>
2  <Flex direction="column" gap={3}>
3    <Flex gap={3} align="center">
4      <Checkbox name="apple" id="cd-apple" />
5      <label htmlFor="cd-apple">Apple</label>
6    </Flex>
7    <Flex gap={3} align="center">
8      <Checkbox name="banana" id="cd-banana" />
9      <label htmlFor="cd-banana">Banana</label>
10    </Flex>
11  </Flex>
12</Checkbox.Group>

Parent Checkbox

Use a parent checkbox with allValues to toggle all items at once.

1(function ParentExample() {
2  const [value, setValue] = React.useState([]);
3  const allValues = ["apple", "banana", "cherry"];
4  return (
5    <Checkbox.Group
6      value={value}
7      onValueChange={setValue}
8      allValues={allValues}
9    >
10      <Flex direction="column" gap={3}>
11        <Flex gap={3} align="center">
12          <Checkbox parent id="cp-all" />
13          <label htmlFor="cp-all">
14            <strong>Select All</strong>
15          </label>

API Reference

The checkbox, and the group that coordinates several.

Root

Renders a toggleable checkbox input.

Prop

Type

Group

Groups multiple checkboxes and manages their shared checked state via a string[] value.

Prop

Type

Slots

Every rendered part carries a stable data-slot attribute for styling and testing:

SlotElement
checkboxThe checkbox control itself
checkbox-indicatorThe indicator inside the control
checkbox-iconThe check or indeterminate icon (when checked or indeterminate)
checkbox-groupThe Checkbox.Group container

Accessibility

  • Follows the WAI-ARIA Checkbox pattern
  • Supports keyboard activation with Space key
  • Uses aria-checked to indicate state (checked, unchecked, indeterminate)
  • Associates with labels via id and htmlFor attributes
  • Wrap Checkbox.Group with aria-label or aria-labelledby for an accessible group name
  • Disabled state preserves the visual checked/indeterminate appearance while preventing interaction
  • Read-only state reduces opacity and changes cursor to indicate non-editable content
  • Invalid state displays a danger border (or danger background when checked/indeterminate) for form validation feedback