The @bento/checkbox package provides accessible and customizable checkbox inputs. It exports the CheckboxGroup and Checkbox primitives, enabling you to build individual or groups of checkboxes with consistent keyboard navigation, focus management, and ARIA support. React Aria is used to ensure that the checkboxes are accessible to all users.

The CheckboxGroup allows a user to select multiple items from a list of Checkbox components.

The Checkbox is a single checkbox option that can be selected by the user.

Installation

npm install --save @bento/checkbox

Props

The following properties are available to be used on the CheckboxGroup and Checkbox primitives:

Checkbox

CheckboxGroup

Data Attributes, Slot Map and Props

Data Attributes

The following data attributes can be used to style and customize the CheckboxGroup and Checkbox primitives.

`CheckboxGroup` Data Attributes

Attribute	Description	Example Values
`data-disabled`	Indicates the checkbox group is disabled	"true"
`data-readonly`	Indicates the checkbox group is readonly	"true"
`data-required`	Indicates the checkbox group is required	"true"
`data-invalid`	Indicates the checkbox group is invalid	"true"

`Checkbox` Data Attributes

Attribute	Description	Example Values
`data-disabled`	Indicates the checkbox is disabled	"true"
`data-readonly`	Indicates the checkbox is readonly	"true"
`data-required`	Indicates the checkbox is required	"true"
`data-invalid`	Indicates the checkbox is invalid	"true"
`data-indeterminate`	Indicates the checkbox is in an indeterminate state	"true"
`data-pressed`	Indicates the checkbox is being pressed	"true"
`data-hovered`	Indicates the checkbox is hovered	"true"
`data-focused`	Indicates the checkbox has focus	"true"
`data-focus-visible`	Indicates focus should be visible	"true"
`data-selected`	Indicates the checkbox is selected	"true"

`CheckboxGroup` Slot Map

Slot Name	Description
`label`	Label for checkbox group
`description`	Description for checkbox group
`error`	Error for checkbox group

`Checkbox` Slot Map

Slot Name	Description
`icon-checked`	Icon for checked checkbox
`icon-unchecked`	Icon for unchecked checkbox
`icon-indeterminate`	Icon for indeterminate checkbox

Examples

Default Checkbox - Uncontrolled

The Checkbox primitive is uncontrolled by default, meaning it manages its own state internally. You can also use it in a controlled manner by providing the checked and onChange props.

/* v8 ignore next */
import React from 'react';
import { Checkbox } from '@bento/checkbox';

export function CheckboxExample(args: React.ComponentProps<typeof Checkbox>) {
  return (
    <Checkbox name="checkbox-example" value="checkbox-value" {...args}>
      Checkbox Label
    </Checkbox>
  );
}

Controlled Checkbox

The Checkbox can also be used in a controlled manner, where you manage its state externally with the checked and onChange props.

/* v8 ignore next */
import React, { useState } from 'react';
import { Checkbox } from '@bento/checkbox';

export function CheckboxControlledExample() {
  const [checked, setChecked] = useState(false);

  return (
    <Checkbox
      name="checkbox-controlled-example"
      value="checkbox-controlled-value"
      isSelected={checked}
      onChange={setChecked}
    >
      Controlled Checkbox
    </Checkbox>
  );
}

Checkbox Group

The CheckboxGroup allows a user to select multiple items from a list of Checkbox components.

/* v8 ignore next */
import React from 'react';
import { Checkbox, CheckboxGroup } from '@bento/checkbox';
import { Text } from '@bento/text';
import { FieldError } from '@bento/field-error';

export function CheckboxGroupExample(args: React.ComponentProps<typeof CheckboxGroup>) {
  return (
    <CheckboxGroup name="checkbox-group-example" {...args}>
      <Text slot="label">Checkbox Group</Text>
      <Checkbox value="checkbox-1">Checkbox 1</Checkbox>
      <Checkbox value="checkbox-2">Checkbox 2</Checkbox>
      <Text slot="description">Select your options</Text>
      <FieldError slot="error">This is an error message</FieldError>
    </CheckboxGroup>
  );
}

Controlled Checkbox Group

The CheckboxGroup can also be used in a controlled manner, where you manage the state of the checkboxes externally with the value and onChange props.

/* v8 ignore next */
import React, { useState } from 'react';
import { Checkbox, CheckboxGroup } from '@bento/checkbox';
import { Text } from '@bento/text';

export function CheckboxGroupControlledExample() {
  const [selectedValues, setSelectedValues] = useState<string[]>([]);

  return (
    <CheckboxGroup value={selectedValues} onChange={setSelectedValues}>
      <Text slot="label">Checkbox Group</Text>
      <Checkbox value="option1">Option 1</Checkbox>
      <Checkbox value="option2">Option 2</Checkbox>
      <Checkbox value="option3">Option 3</Checkbox>
    </CheckboxGroup>
  );
}

Checkbox Group with Indeterminate State

The CheckboxGroup can also support an indeterminate state, which is useful when some but not all checkboxes are selected. The complex state management shown here is an example of how to handle indeterminate states in a checkbox group in a common way.

/* v8 ignore next */
import React, { useState } from 'react';
import { Checkbox, CheckboxGroup } from '@bento/checkbox';
import { Text } from '@bento/text';

export function CheckboxGroupIndeterminateExample() {
  const [checkedItems, setCheckedItems] = useState<Set<string>>(new Set());

  const items = [
    { id: 'option1', label: 'Option 1' },
    { id: 'option2', label: 'Option 2' },
    { id: 'option3', label: 'Option 3' }
  ];

  const allItemIds = items.map(function getItemId(item) {
    return item.id;
  });
  const isAllSelected = checkedItems.size === items.length;
  const isIndeterminate = checkedItems.size > 0 && checkedItems.size < items.length;

  function handleSelectAll(checked: boolean) {
    if (checked) {
      setCheckedItems(new Set([...allItemIds, 'select-all']));
    } else {
      setCheckedItems(new Set());
    }
  }

  function handleItemChange(itemId: string, checked: boolean) {
    setCheckedItems(function updateCheckedItems(prev) {
      const newSet = new Set(prev);
      if (checked) {
        newSet.add(itemId);
        if (
          allItemIds.every(function checkItemInSet(id) {
            return newSet.has(id);
          })
        ) {
          newSet.add('select-all');
        }
      } else {
        newSet.delete(itemId);
        newSet.delete('select-all');
      }
      return newSet;
    });
  }

  return (
    <CheckboxGroup value={Array.from(checkedItems)} data-value={Array.from(checkedItems)}>
      <Text slot="label">Select Items</Text>
      <Checkbox
        name="select-all"
        value="select-all"
        isSelected={isAllSelected}
        isIndeterminate={isIndeterminate}
        onChange={handleSelectAll}
      >
        Select All
      </Checkbox>

      {items.map((item) => (
        <Checkbox
          key={item.id}
          name={item.id}
          value={item.id}
          isSelected={checkedItems.has(item.id)}
          onChange={function handleItemChangeForItem(checked) {
            return handleItemChange(item.id, checked);
          }}
        >
          {item.label}
        </Checkbox>
      ))}
    </CheckboxGroup>
  );
}