CheckboxGroup
Preview appears after the next Storybook update.
<CheckboxGroup />When to use
Use it for
- Users may pick zero, one or several options from a short visible list (up to about seven).
- Use allValues plus <Checkbox parent /> for a Select all at the top of a long list.
Not for
- Only one option can be picked: use RadioGroup.
- More than about seven options or a searchable list: use Combobox with multiple selection.
Do and don't
Every example is rendered with the real component, so it always matches what ships.
Ask the question in the legend
The legend is read before each option, so it gives every label its context.
A group without a legend
Screen reader users hear "Light, checkbox" with no idea what it is for.
Accessibility
- Native fieldset and legend: the legend names the group; disabled on the fieldset disables every item.
- description and error are linked to the fieldset with aria-describedby; the error carries an icon and text.
- The parent checkbox is checked, unchecked or mixed (aria-checked) based on the children, driven by Base UI.
- Each item keeps its own label and description, so items can be reached and understood one by one.
Content guidelines
- Legend as a short question or noun phrase: "Notify me about", "Platforms".
- Options in a logical order (frequency, then alphabetical), parallel in grammar.
- Errors say what to pick: "Pick at least one reviewer group."
From the code Generated from the component, not editable here.
Anatomy and tokens
Read from packages/react/src/components/CheckboxGroup/CheckboxGroup.module.css at build time. Every value is a token: open one to see its alias chain in both themes.
- Fieldset container
.fieldset - Legend (group label)
.legend - Fieldset container, disabled
.fieldset:disabled .legend - hiddenLegend
.hiddenLegend - required
.required - Description
.description, .error - Description
.description - Error message
.error - errorIcon
.errorIcon - Item list
.group - horizontal
.horizontal - Item list
.group:has(> [data-parent]) > :not([data-parent]) - Fieldset container
.fieldset[data-invalid] [role="checkbox"]:not([data-checked], [data-indeterminate], [data-disabled])
Motion and interaction
CheckboxGroup animates on hover. Try it in the preview at the top.
| When | What changes | Duration | Easing |
|---|---|---|---|
| Hover | Background and border | motion.duration.instant75 ms | motion.easing.standardsettles in place |
With reduced motion turned on, every change happens at once.
From the code Generated from the component, not editable here.
Props
Parsed from the TypeScript types in packages/react/src/components/CheckboxGroup/CheckboxGroup.tsx, so this table cannot drift from the code.
| Prop | Type | Default | Description |
|---|---|---|---|
labelrequired | ReactNode | none | Group label, rendered as the fieldset legend. |
childrenrequired | ReactNode | none | Checkbox items, each with a `value`. |
description | ReactNode | none | Help under the legend. |
error | ReactNode | none | Error for the group, for example "Pick at least one reviewer." Linked with aria-describedby. |
value | string[] | none | Values of the checked items (controlled). |
defaultValue | string[] | none | No description in the code yet. |
onValueChange | (value: string[]) => void | none | No description in the code yet. |
allValues | string[] | none | Every item value. Required for a parent "Select all" checkbox: add `<Checkbox parent label="All" />` and the group drives its checked and mixed state. |
orientation | 'vertical' | 'horizontal' | 'vertical' | Default `vertical`. |
disabled | boolean | none | No description in the code yet. |
required | boolean | false | No description in the code yet. |
hideLabel | boolean | false | No description in the code yet. |
className | string | none | No description in the code yet. |
Playground
Change the props and see the real CheckboxGroup update. Controls are generated from the TypeScript props; nothing here changes the system.
<CheckboxGroup label="Notify me about" />Workbench
For contributors: every state with the accessibility panel, in the component workbench (Storybook). The stories double as visual test fixtures; the guidance on this page is the user documentation (open CheckboxGroup in Storybook).
Embed Storybook stories here (4)
Loads from https://bridge-storybook.floriangouloubi.com (set STORYBOOK_URL at build time). If Storybook is not running, the frames stay empty.
Default
SelectAll
Invalid
AllStates
From the code Generated from the component, not editable here.
Changelog
No release note mentions CheckboxGroup yet.