A CheckboxGroup allows users to select one or more items from a list of choices.
Value
Use the value or defaultValue prop to set the selected items, and onChange to handle selection changes.
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';
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" styles={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 | ||
value | string | Default: — |
The current value (controlled). | ||
defaultValue | string | Default: — |
The default value (uncontrolled). | ||
onChange | | Default: — |
Handler that is called when the value changes. | ||