React Aria
DocsReleasesBlog
React Aria

CheckboxGroup

A checkbox group allows a user to select multiple items from a list of options.

Theme 
Favorite sports
 
 
isDisabled 
Example
CheckboxGroup.tsx
CheckboxGroup.css
import {CheckboxGroup} from './CheckboxGroup';
import {Checkbox} from './Checkbox';

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

Value

Use the value or defaultValue prop to set the selected items, and onChange to handle selection changes.

Favorite sports

Current selection: soccer, baseball

import {CheckboxGroup} from './CheckboxGroup';
import {Checkbox} from './Checkbox';
import {useState} from 'react';

function Example() {
  let [selected, setSelected] = useState(['soccer', 'baseball']);

  return (
    <>
      <CheckboxGroup
        label="Favorite sports"
        value={selected}
        onChange={setSelected}>
        <Checkbox value="soccer">Soccer</Checkbox>
        <Checkbox value="baseball">Baseball</Checkbox>
        <Checkbox value="basketball">Basketball</Checkbox>
      </CheckboxGroup>
      <p>Current selection: {selected.join(', ')}</p>
    </>
  );
}

Forms

Use the name prop to submit the selected checkboxes to the server. Set the isRequired prop on the <CheckboxGroup> to validate the user selects at least one checkbox, or on individual checkboxes. See the Forms guide to learn more.

Sandwich condiments
Agree to the following
import {CheckboxGroup} from './CheckboxGroup';
import {Checkbox} from './Checkbox';
import {Button} from './Button';
import {Form} from './Form';;

<Form>
  <div style={{display: 'flex', gap: 32, flexWrap: 'wrap'}}>
    <CheckboxGroup
      label="Sandwich condiments"
      name="condiments"
      isRequired>
      <Checkbox value="lettuce">Lettuce</Checkbox>
      <Checkbox value="tomato">Tomato</Checkbox>
      <Checkbox value="onion">Onion</Checkbox>
      <Checkbox value="sprouts">Sprouts</Checkbox>
    </CheckboxGroup>
    <CheckboxGroup label="Agree to the following" name="terms">
      <Checkbox value="terms" isRequired>Terms and conditions</Checkbox>
      <Checkbox value="privacy" isRequired>Privacy policy</Checkbox>
      <Checkbox value="cookies" isRequired>Cookie policy</Checkbox>
    </CheckboxGroup>
  </div>
  <Button type="submit" style={{marginTop: 8}}>Submit</Button>
</Form>

API

Shows a checkbox group component with labels pointing to its parts, including the checkbox group label, and group element containing three checkboxes with input and label elements.ShoppingMusicTravelInterestsInputCheckbox group labelGroupCheckbox label 
<CheckboxGroup>
  <Label />
  <Checkbox />
  <Text slot="description" />
  <FieldError />
</CheckboxGroup>

CheckboxGroup

NameType
isDisabledboolean

Whether the input is disabled.

isReadOnlyboolean

Whether the input can be selected but not changed by the user.

children<>

The children of the component. A function may be provided to alter the children based on component state.

valuestring[]

The current value (controlled).

defaultValuestring[]

The default value (uncontrolled).

onChange(value: T) => void

Handler that is called when the value changes.

Default className: react-aria-CheckboxGroup

Render PropCSS Selector
isDisabledCSS Selector: [data-disabled]
Whether the checkbox group is disabled.
isReadOnlyCSS Selector: [data-readonly]
Whether the checkbox group is read only.
isRequiredCSS Selector: [data-required]
Whether the checkbox group is required.
isInvalidCSS Selector: [data-invalid]
Whether the checkbox group is invalid.
stateCSS Selector: —
State of the checkbox group.

Related pages