CheckboxGroup

A CheckboxGroup allows users to select one or more items from a list of choices.

import {CheckboxGroup, Checkbox} from '@react-spectrum/s2';

<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.

import {CheckboxGroup, Checkbox} from '@react-spectrum/s2';
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.

import {CheckboxGroup, Checkbox, Button, Form} from '@react-spectrum/s2';
import {style} from '@react-spectrum/s2/style' with {type: 'macro'};

<Form>
  <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>
  <Button type="submit" className={style({marginTop: 8})}>Submit</Button>
</Form>

API

<CheckboxGroup>
  <Checkbox />
</CheckboxGroup>

CheckboxGroup

Testing

Test utils

@react-spectrum/test-utils offers common checkbox group interaction utilities which you may find helpful when writing tests. To install, simply add it to your dev dependencies via your preferred package manager.

yarn add @react-spectrum/test-utils --dev

Once installed, you can access the User that @react-spectrum/test-utils provides in your test file as shown below. This user only needs to be initialized once and then can be used to generate the CheckboxGroup tester in your test cases. This gives you access to CheckboxGroup specific utilities that you can then call within your test to query for specific subcomponents or simulate common interactions. The example test case below shows how you might go about setting up the CheckboxGroup tester, use it to simulate checkbox selection, and verify the checkbox group's state after each interaction.

// CheckboxGroup.test.ts
import {render} from '@testing-library/react';
import {User} from '@react-spectrum/test-utils';

let testUtilUser = new User({interactionType: 'mouse', advanceTimer: jest.advanceTimersByTime});
// ...

it('CheckboxGroup can select multiple checkboxes', async function () {
  // Render your test component/app and initialize the checkbox group tester
  let {getByTestId} = render(
    <CheckboxGroup data-testid="test-checkboxgroup">
    ...
    </CheckboxGroup>
  );
  let checkboxGroupTester = testUtilUser.createTester('CheckboxGroup', {root: getByTestId('test-checkboxgroup')});
  expect(checkboxGroupTester.selectedCheckboxes).toHaveLength(0);

  await checkboxGroupTester.toggleCheckbox({checkbox: 0});
  expect(checkboxGroupTester.checkboxes[0]).toBeChecked();
  expect(checkboxGroupTester.selectedCheckboxes).toHaveLength(1);

  await checkboxGroupTester.toggleCheckbox({checkbox: 4});
  expect(checkboxGroupTester.checkboxes[4]).toBeChecked();
  expect(checkboxGroupTester.selectedCheckboxes).toHaveLength(2);
});

See below for the full definition of the User and the CheckboxGroup tester.

Properties

Methods

Properties

Methods

Testing FAQ