import { Meta, ArgTypes, Story, Controls, Source, } from '@storybook/addon-docs/blocks';

Checkbox

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

| Prop | Type | Required | Description | |------|------|----------|------------| | value | string | No | The value of the checkbox, used when submitting an HTML form. | | name | string | No | The name of the checkbox. | | inputRef | Ref<HTMLInputElement> | No | A ref for the HTML input element. | | children | ReactNode | No | The label for the checkbox. Accepts any renderable node. | | isRequired | boolean | No | Whether the checkbox is required or not. | | isReadOnly | boolean | No | Whether the input can be selected but not changed by the user. | | isDisabled | boolean | No | Whether the checkbox is disabled or not. Shows that a selection exists, but is not available in that circumstance. | | autoFocus | boolean | No | Whether the element should receive focus on render. | | isIndeterminate | boolean | No | Whether the checkbox is in an indeterminate state. | | isSelected | boolean | No | Whether the checkbox is in a selected state. | | slot | string | No | A named part of a component that can be customized. This is implemented by the consuming component. The exposed slot names of a component are available in the components documentation. | | slots | Record<string, object \| Function> | No | An object that contains the customizations for the slots. The main way you interact with the slot system as a consumer. | | ref | Ref<HTMLDivElement> \| LegacyRef<Component<CheckboxProps & Slots, any, any>> | No | Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref). @see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs} | | as | "div" | No | |

CheckboxGroup

| Prop | Type | Required | Description | |------|------|----------|------------| | value | string[] | No | The current value of the checkbox group (controlled). | | defaultValue | string[] | No | The default value of the checkbox group (uncontrolled). | | isDisabled | boolean | No | Whether the input is disabled. | | isReadOnly | boolean | No | Whether the input can be selected but not changed by the user. | | isRequired | boolean | No | Whether user input is required on the input before form submission. | | isInvalid | boolean | No | Whether the input value is invalid. | | name | string | No | The name of the input element, used when submitting an HTML form. | | form | string | No | The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document. | | children | ReactNode | No | Checkbox children. | | slot | string | No | A named part of a component that can be customized. This is implemented by the consuming component. The exposed slot names of a component are available in the components documentation. | | slots | Record<string, object \| Function> | No | An object that contains the customizations for the slots. The main way you interact with the slot system as a consumer. | | ref | Ref<HTMLDivElement> \| LegacyRef<Component<CheckboxGroupProps & Slots, any, any>> | No | Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref). @see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs} | | as | "div" | No | |

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>
  );
}