CheckboxGroup

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

Email Notification Preferences

Product UpdatesGet notified about new features and improvements

Security AlertsImportant notifications about your account safety

Marketing EmailsReceive promotions, offers, and newsletters

label

size

orientation

labelPosition

description

contextualHelp

isEmphasized

isDisabled

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

<CheckboxGroup label="Email Notification Preferences">
  <Checkbox
    value="product"
    description="Get notified about new features and improvements">
    Product Updates
  </Checkbox>
  <Checkbox
    value="security"
    description="Important notifications about your account safety">
    Security Alerts
  </Checkbox>
  <Checkbox
    value="marketing"
    description="Receive promotions, offers, and newsletters">
    Marketing Emails
  </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/CheckboxGroup';
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} from '@react-spectrum/s2/CheckboxGroup';
import {Button} from '@react-spectrum/s2/Button';
import {Form} from '@react-spectrum/s2/Form';
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>

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.

CheckboxGroup

Value

Forms

API

CheckboxGroup

Related pages