Checkbox Group
Coordinates independently toggleable values under one accessible group.
Contract
| Decision | Choose |
|---|---|
| value ownership | defaultValue for uncontrolled state, or value with onValueChange |
| availability | group disabled, or item-level readOnly when values must remain available to forms |
| form | give child checkboxes the same name; each checked child contributes its value |
| parent choice | provide allValues and a child checkbox with parent |
| validation | validate the controlled array when selection-count rules exceed native required semantics |
Name the group with aria-label or aria-labelledby, and name every child checkbox. Wrap each child in a TRField.Item with a TRField.Label: the item scopes its label to the checkbox inside it, so repeated options need no id or htmlFor. Every TRField.Item needs a TRField.Root ancestor, so wrap the item — or the whole group — in one TRField.Root. A group coordinates independent choices; use TRRadioGroup when exactly one value may be selected.
Install
pnpm add @tinyrack/uiScroll inside the code area to read long lines.
Styles
@import '@tinyrack/ui/components/checkbox-group.css';Scroll inside the code area to read long lines.
Imports
import { TRCheckboxGroup } from '@tinyrack/ui/components/checkbox-group';
import { TRCheckbox } from '@tinyrack/ui/components/checkbox';Scroll inside the code area to read long lines.
Playground
Usage
Examples
Set availability for the whole set
Validate a selection count
Choose one or two values permalink
Control the value array when product rules require a minimum and maximum count.
Add a select-all parent
Parent and mixed state permalink
The parent is checked when all values are selected and mixed when only some are selected.
Associate an external form
External owner and reset permalink
Set `form` on every child checkbox. Reset restores the group's uncontrolled `defaultValue`.
API
Value and availability
| Prop | Type / default | Purpose |
|---|---|---|
value, defaultValue | string[], [] | Controls or initializes selected child values. |
onValueChange | (value, details) => void | Reports the next value array. |
disabled | boolean, false | Disables every child and suppresses its form data. |
allValues | string[] | Defines the complete set used by a parent checkbox. |
Composition and forms
Render TRCheckbox.Root children with distinct value values and shared name values. readOnly belongs on the child checkbox; it is not a group prop. Form ownership also belongs to each hidden checkbox input. Uncontrolled groups restore defaultValue on reset, while controlled groups remain governed by value.
The root preserves Base UI render, ref, events, native attributes, and state-driven className and style. The module exports TRCheckboxGroup, TRCheckboxGroupProps, and TRCheckboxGroupState; CSS is opt-in.