CheckboxGroup

CheckboxGroup renders a set of Checkboxes.

Page navigation navigation

React

readyNot reviewed for a11y

Storybook|Source

Rails

readyNot reviewed for a11y

Docs|Lookbook|Source

Figma

View in Figma|

React examples

Default

Choices

Choice one

Choice two

Choice three

<CheckboxGroup>
  <CheckboxGroup.Label>Choices</CheckboxGroup.Label>
  <FormControl>
    <Checkbox value="one" />
    <FormControl.Label>Choice one</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="two" />
    <FormControl.Label>Choice two</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="three" />
    <FormControl.Label>Choice three</FormControl.Label>
  </FormControl>
</CheckboxGroup>

<CheckboxGroup>
  <CheckboxGroup.Label>Choices</CheckboxGroup.Label>
  <FormControl>
    <Checkbox value="one" />
    <FormControl.Label>Choice one</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="two" />
    <FormControl.Label>Choice two</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="three" />
    <FormControl.Label>Choice three</FormControl.Label>
  </FormControl>
</CheckboxGroup>

With a caption

ChoicesCaption about the choices

Choice one

Choice two

Choice three

<CheckboxGroup>
  <CheckboxGroup.Label>Choices</CheckboxGroup.Label>
  <CheckboxGroup.Caption>Caption about the choices</CheckboxGroup.Caption>
  <FormControl>
    <Checkbox value="one" />
    <FormControl.Label>Choice one</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="two" />
    <FormControl.Label>Choice two</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="three" />
    <FormControl.Label>Choice three</FormControl.Label>
  </FormControl>
</CheckboxGroup>

<CheckboxGroup>
  <CheckboxGroup.Label>Choices</CheckboxGroup.Label>
  <CheckboxGroup.Caption>Caption about the choices</CheckboxGroup.Caption>
  <FormControl>
    <Checkbox value="one" />
    <FormControl.Label>Choice one</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="two" />
    <FormControl.Label>Choice two</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="three" />
    <FormControl.Label>Choice three</FormControl.Label>
  </FormControl>
</CheckboxGroup>

With a validation message

See the form pattern documentation for more information on form validation patterns.

ChoicesSomething went wrong

Choice one

Choice two

Choice three

Something went wrong

<CheckboxGroup>
  <CheckboxGroup.Label>Choices</CheckboxGroup.Label>
  <FormControl>
    <Checkbox value="one" />
    <FormControl.Label>Choice one</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="two" />
    <FormControl.Label>Choice two</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="three" />
    <FormControl.Label>Choice three</FormControl.Label>
  </FormControl>
  <CheckboxGroup.Validation variant="error">Something went wrong</CheckboxGroup.Validation>
</CheckboxGroup>

<CheckboxGroup>
  <CheckboxGroup.Label>Choices</CheckboxGroup.Label>
  <FormControl>
    <Checkbox value="one" />
    <FormControl.Label>Choice one</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="two" />
    <FormControl.Label>Choice two</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="three" />
    <FormControl.Label>Choice three</FormControl.Label>
  </FormControl>
  <CheckboxGroup.Validation variant="error">Something went wrong</CheckboxGroup.Validation>
</CheckboxGroup>

More code examples

See the CheckboxGroup Storybook stories

Selection required

Choices

Choice one

Choice two

Choice three

<CheckboxGroup required>
  <CheckboxGroup.Label>Choices</CheckboxGroup.Label>
  <FormControl>
    <Checkbox value="one" />
    <FormControl.Label>Choice one</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="two" />
    <FormControl.Label>Choice two</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="three" />
    <FormControl.Label>Choice three</FormControl.Label>
  </FormControl>
</CheckboxGroup>

<CheckboxGroup required>
  <CheckboxGroup.Label>Choices</CheckboxGroup.Label>
  <FormControl>
    <Checkbox value="one" />
    <FormControl.Label>Choice one</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="two" />
    <FormControl.Label>Choice two</FormControl.Label>
  </FormControl>
  <FormControl>
    <Checkbox value="three" />
    <FormControl.Label>Choice three</FormControl.Label>
  </FormControl>
</CheckboxGroup>

Props

CheckboxGroup

Name	Default	Description
aria-labelledby		`string` Used when associating the input group with a label other than CheckboxGroup.Label
children Required		`CheckboxGroup.Label \| CheckboxGroup.Caption \| CheckboxGroup.Validation \| FormControl`
disabled	`false`	`boolean` Whether the input group allows user input
id	`a generated string`	`string` The unique identifier for this input group. Used to associate the label, validation text, and caption text. You may want a custom ID to make it easier to select elements in integration tests.
onChange		`(selected: string[], e?: ChangeEvent<HTMLInputElement>) => void` An onChange handler that gets called when the selection changes
required	`false`	`boolean` If true, the user must make a selection before the owning form can be submitted
sx		`SystemStyleObject`

CheckboxGroup.Label

Name	Default	Description
visuallyHidden	`false`	`boolean` If true, the fieldset legend will be visually hidden
sx		`SystemStyleObject`

CheckboxGroup.Caption

Name	Default	Description
children		`React.ReactNode` The caption content
sx		`SystemStyleObject`

CheckboxGroup.Validation

Name	Default	Description
children		`React.ReactNode` The validation message
variant Required		`'error' \| 'success'` Changes the visual style to match the validation status
sx		`SystemStyleObject`