Primitives
Checkbox group
Several independent choices sharing one tab stop
EmailEvery change
PushDesktop app
SMSMobile only
1 of 3 channels
Usage
import { CheckboxGroup } from "@gpuixui/primitives";
<CheckboxGroup
label="Channels"
value={channels}
onValueChange={setChannels}
options={[
{ value: "email", label: "Email" },
{ value: "push", label: "Push", description: "Desktop app" },
{ value: "sms", label: "SMS", disabled: true },
]}
/>;API
CheckboxGroup
| Prop | Type | Default | Consequence |
|---|---|---|---|
options | ReadonlyArray<GroupOption> | — | the choices as data; omit with item children |
children | ReactNode | — | CheckboxGroupItem elements, for rich content |
value | ReadonlyArray<string> | — | controlled values |
defaultValue | ReadonlyArray<string> | [] | the initial values when uncontrolled |
onValueChange | (next: ReadonlyArray<string>) => void | none | the on values |
onChange | (next: ReadonlyArray<string>) => void | none | deprecated alias for onValueChange |
orientation | "vertical" | "horizontal" | "vertical" | which arrow pair moves focus; a name this release does not carry reads as "vertical" |
size | "sm" | "md" | "lg" | "md" | box side from iconSize |
accent | "primary" | "destructive" | "primary" | the fill and mark colour; a stored name the table does not carry reads as primary |
disabled | boolean | false | disables every option |
invalid | boolean | false | the empty box's border and every row's focus ring take the destructive role |
label | string | none | the group's accessible name |
description | string | none | announced help on the group node |
ref / aria-id / onLayout | host props | none | land on the row that holds the tab stop |
style | StateStyle<CheckboxGroupState> | — | resolved against the live state, merged last |
itemStyle | StateStyle<CheckboxItemState> | — | resolved per option row, merged last |
onClick / onKeyDown / onKeyUp / onFocus / onBlur | host handlers | none | composed with the group's own; yours runs first |
className | string | — | compiled after the recipe, so it wins conflicts |
testId | string | — | stable locator for the group |
itemTestId | (value: string) => string | — | per-row locator, derived from its value |
CheckboxGroupItem
| Prop | Type | Default | Consequence |
|---|---|---|---|
value | string | — | the value this option adds |
label | string | — | accessible name, and the visible text unless children replaces it |
description | string | none | a caption beside the name, announced as the row's help (aria-description); a blank one paints and announces nothing |
disabled | boolean | false | the option cannot be chosen and takes no focus |
children | ReactNode | — | rich content drawn instead of the name pair |
Keyboard
- Arrow UpArrow DownArrow LeftArrow Right
- moves focus along the group's orientation
- HomeEnd
- the first or last option
- EnterSpace
- toggles the focused option
A typed prefix moves focus to the first matching option without toggling it.
read from CheckboxGroup.tsx
Edit this page on GitHubpackages/primitives/docs/checkbox-group.mdx