CheckboxGroup

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

Favorite sports

Soccer

Baseball

Basketball

label

size

orientation

labelPosition

description

contextualHelp

isEmphasized

isDisabled

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.

Favorite sports

Soccer

Baseball

Basketball

Current selection: soccer, baseball

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';

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

API

<CheckboxGroup>
  <Checkbox />
</CheckboxGroup>

CheckboxGroup

Name	Type	Default
`size`	`'S' \| 'M' \| 'L' \| 'XL'`	Default: `'M'`
The size of the Checkboxes in the CheckboxGroup.
`orientation`	`Orientation`	Default: `'vertical'`
The axis the checkboxes should align with.
`children`	`ReactNode`	Default: —
The Checkboxes contained within the CheckboxGroup.
`isEmphasized`	`boolean`	Default: —
By default, checkboxes are not emphasized (gray). The emphasized (blue) version provides visual prominence.
`isDisabled`	`boolean`	Default: —
Whether the input is disabled.
`isReadOnly`	`boolean`	Default: —
Whether the input can be selected but not changed by the user.
`styles`	`StylesProp`	Default: —
Spectrum-defined styles, returned by the `style()` macro.

`value`	`string[]`	Default: —
The current value (controlled).
`defaultValue`	`string[]`	Default: —
The default value (uncontrolled).
`onChange`	`(value: T) => void`	Default: —
Handler that is called when the value changes.