useCheckboxGroup

Provides the behavior and accessibility implementation for a checkbox group component. Checkbox groups allow users to select multiple items from a list of options.

API#

Features#

Checkbox groups can be built in HTML with the <fieldset> and <input> elements, however these can be difficult to style. useCheckboxGroup and useCheckboxGroupItem help achieve accessible checkbox groups that can be styled as needed.

• Checkbox groups are exposed to assistive technology via ARIA
• Each checkbox is built with a native HTML <input> element, which can be optionally visually hidden to allow custom styling
• Full support for browser features like form autofill
• Keyboard focus management and cross browser normalization
• Group and checkbox labeling support for assistive technology

Anatomy#

A checkbox group consists of a set of checkboxes, and a label. Each checkbox includes a label and a visual selection indicator. Zero or more checkboxes within the group can be selected at a time. Users may click or touch a checkbox to select it, or use the Tab key to navigate to it and the Space key to toggle it.

useCheckboxGroup returns props for the group and its label, which you should spread onto the appropriate element:

useCheckboxGroupItem returns props for an individual checkbox:

Selection state is managed by the useCheckboxGroupState hook in @react-stately/checkbox. The state object should be passed as an option to useCheckboxGroup and useCheckboxGroupItem.

Individual checkboxes must have a visual label. If the checkbox group does not have a visible label, an aria-label or aria-labelledby prop must be passed instead to identify the element to assistive technology.

Note: useCheckboxGroupItem should only be used when it is contained within a checkbox group. For a standalone checkbox, use the useCheckbox hook instead.

Example#

This example uses native input elements for the checkboxes, and React context to share state from the group to each checkbox. An HTML <label> element wraps the native input and the text to provide an implicit label for the radio.

import {useCheckboxGroup, useCheckboxGroupItem} from '@react-aria/checkbox';
import {useCheckboxGroupState} from '@react-stately/checkbox';

let CheckboxGroupContext = React.createContext(null);

function CheckboxGroup(props) {
  let {children, label} = props;
  let state = useCheckboxGroupState(props);
  let {groupProps, labelProps} = useCheckboxGroup(props, state);

  return (
    <div {...groupProps}>
      <span {...labelProps}>{label}</span>
      <CheckboxGroupContext.Provider value={state}>
        {children}
      </CheckboxGroupContext.Provider>
    </div>
  );
}

function Checkbox(props) {
  let {children} = props;
  let state = React.useContext(CheckboxGroupContext);
  let ref = React.useRef();
  let {inputProps} = useCheckboxGroupItem(props, state, ref);

  let isDisabled = state.isDisabled || props.isDisabled;
  let isSelected = state.isSelected(props.value);

  return (
    <label
      style={{
        display: 'block',
        color: (isDisabled && 'var(--gray)') || (isSelected && 'var(--blue)'),
      }}>
      <input {...inputProps} ref={ref} />
      {children}
    </label>
  );
}

<CheckboxGroup label="Favorite sports">
  <Checkbox value="soccer" isDisabled>Soccer</Checkbox>
  <Checkbox value="baseball">Baseball</Checkbox>
  <Checkbox value="basketball">Basketball</Checkbox>
</CheckboxGroup>

import {
  useCheckboxGroup,
  useCheckboxGroupItem
} from '@react-aria/checkbox';
import {useCheckboxGroupState} from '@react-stately/checkbox';

let CheckboxGroupContext = React.createContext(null);

function CheckboxGroup(props) {
  let { children, label } = props;
  let state = useCheckboxGroupState(props);
  let { groupProps, labelProps } = useCheckboxGroup(
    props,
    state
  );

  return (
    <div {...groupProps}>
      <span {...labelProps}>{label}</span>
      <CheckboxGroupContext.Provider value={state}>
        {children}
      </CheckboxGroupContext.Provider>
    </div>
  );
}

function Checkbox(props) {
  let { children } = props;
  let state = React.useContext(CheckboxGroupContext);
  let ref = React.useRef();
  let { inputProps } = useCheckboxGroupItem(
    props,
    state,
    ref
  );

  let isDisabled = state.isDisabled || props.isDisabled;
  let isSelected = state.isSelected(props.value);

  return (
    <label
      style={{
        display: 'block',
        color: (isDisabled && 'var(--gray)') ||
          (isSelected && 'var(--blue)')
      }}
    >
      <input {...inputProps} ref={ref} />
      {children}
    </label>
  );
}

<CheckboxGroup label="Favorite sports">
  <Checkbox value="soccer" isDisabled>Soccer</Checkbox>
  <Checkbox value="baseball">Baseball</Checkbox>
  <Checkbox value="basketball">Basketball</Checkbox>
</CheckboxGroup>

import {
  useCheckboxGroup,
  useCheckboxGroupItem
} from '@react-aria/checkbox';
import {useCheckboxGroupState} from '@react-stately/checkbox';

let CheckboxGroupContext =
  React.createContext(
    null
  );

function CheckboxGroup(
  props
) {
  let {
    children,
    label
  } = props;
  let state =
    useCheckboxGroupState(
      props
    );
  let {
    groupProps,
    labelProps
  } = useCheckboxGroup(
    props,
    state
  );

  return (
    <div {...groupProps}>
      <span
        {...labelProps}
      >
        {label}
      </span>
      <CheckboxGroupContext.Provider
        value={state}
      >
        {children}
      </CheckboxGroupContext.Provider>
    </div>
  );
}

function Checkbox(
  props
) {
  let { children } =
    props;
  let state = React
    .useContext(
      CheckboxGroupContext
    );
  let ref = React
    .useRef();
  let { inputProps } =
    useCheckboxGroupItem(
      props,
      state,
      ref
    );

  let isDisabled =
    state.isDisabled ||
    props.isDisabled;
  let isSelected = state
    .isSelected(
      props.value
    );

  return (
    <label
      style={{
        display: 'block',
        color:
          (isDisabled &&
            'var(--gray)') ||
          (isSelected &&
            'var(--blue)')
      }}
    >
      <input
        {...inputProps}
        ref={ref}
      />
      {children}
    </label>
  );
}

<CheckboxGroup label="Favorite sports">
  <Checkbox
    value="soccer"
    isDisabled
  >
    Soccer
  </Checkbox>
  <Checkbox value="baseball">
    Baseball
  </Checkbox>
  <Checkbox value="basketball">
    Basketball
  </Checkbox>
</CheckboxGroup>

Styling#

See the useCheckbox docs for details on how to customize the styling of checkbox elements.