CheckboxGroup
StableSeveral independent choices under one question, in a fieldset with a legend. An optional parent checkbox selects or clears the whole group and shows a mixed state.
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.
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])
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 |
|---|---|---|---|
label required | ReactNode | none | Group label, rendered as the fieldset legend. |
children required | 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
Changelog
- New
Forms: Field (label, description, error wired by Base UI Field) and Input rebuilt on it (prefix, suffix, sizes; label, hint and error props kept). New Textarea (autosize, character count), Select (groups, descriptions), Combobox (filtering, async loading and empty states, multiple with chips), Checkbox (indeterminate, parent), CheckboxGroup, RadioGroup, Switch, Slider (single and range), NumberField (steppers, units) and Form (server errors with a focusable error summary, FormActions footer).
Unreleased (current version 0.1.0, no release tagged yet) , Oct 17, 2026