Chapter 17: Checkbox Group

Core Idea

A one-part wrapper around multiple Checkbox.Root children that manages a combined array value and enables a "parent" checkbox that auto-derives its own indeterminate/checked state from its children's state.

Key Concepts

• Anatomy: CheckboxGroup (from @base-ui/react/checkbox-group) wraps plain Checkbox.Root children (imported from @base-ui/react/checkbox) — the group itself renders one element, not a part hierarchy.
• Labeling: aria-labelledby pointing at a sibling label element for the group as a whole; each individual Checkbox.Root still needs its own label (wrapping <label>, sibling htmlFor, or Field.Label).
• Group value: value/defaultValue/onValueChange on CheckboxGroup is the array of checked checkbox values combined across all children.
• Parent ("select all") checkbox pattern: 1) make CheckboxGroup controlled, 2) pass every child's value in allValues on CheckboxGroup, 3) add parent boolean prop to the designated parent Checkbox.Root. The group then automatically drives that parent checkbox's indeterminate state when some-but-not-all children are checked.
• Form integration: wrap in <Field.Root name="..."> + <Fieldset.Root render={<CheckboxGroup />}> + <Fieldset.Legend>, with each option in <Field.Item> — the same Fieldset-grouping pattern used for Radio Group (ch009 Forms).

Reference Tables

Part	Notable props	Notable data attributes
CheckboxGroup	value/defaultValue/onValueChange, allValues, disabled	data-disabled

Key Takeaways

1. The "select all" parent-checkbox pattern requires all three steps together (controlled group + allValues + parent on one child) — omitting allValues leaves the group unable to compute indeterminate state correctly.
2. Use Fieldset.Root render={<CheckboxGroup />} + Fieldset.Legend (not a bare <div> + heading) so the group's accessible name comes for free via the same mechanism as Radio Group.
3. Individual checkboxes inside the group still follow all of Checkbox's own labeling rules (ch016) — the group only manages the combined value, not per-item accessibility.

Connects To

• ch016 (Checkbox): parent/indeterminate props live on the individual Checkbox.Root, documented in full there.
• ch024 (Fieldset): the Legend/grouping pattern used for accessible group naming.
• ch036 (Radio): the mutually-exclusive sibling of this multi-select group pattern.