Primitives
Toggle group
A toolbar of related modes, pressed and unpressed
Multiple · formatting
Single · view
Usage
import { ToggleGroup } from "@gpuixui/primitives";
<ToggleGroup
type="multiple"
label="Formatting"
value={formats}
onValueChange={setFormats}
options={[
{ value: "bold", label: "Bold" },
{ value: "italic", label: "Italic" },
]}
/>;API
ToggleGroup
| Prop | Type | Default | Consequence |
|---|---|---|---|
type | "single" | "multiple" | "multiple" | at most one pressed value, or any number |
options | ReadonlyArray<GroupOption> | — | the choices as data; omit with item children |
children | ReactNode | — | ToggleGroupItem elements, for rich content |
value | string | ReadonlyArray<string> | — | controlled pressed values |
defaultValue | string | ReadonlyArray<string> | [] | the initial pressed values |
onValueChange | (next: string | ReadonlyArray<string>) => void | none | the pressed values, shaped by type |
orientation | "vertical" | "horizontal" | "horizontal" | the group's stack direction and arrow pair; a name this release does not carry reads as "horizontal" |
variant | "default" | "outline" | "default" | no chrome at rest, or a border |
size | "sm" | "md" | "lg" | "md" | from the density scale |
square | boolean | false | equal width and height per option |
disabled | boolean | false | disables every option and removes the group's stop |
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 option that holds the tab stop |
style | StateStyle<ToggleGroupState> | — | resolved against the group's live state, merged last |
itemStyle | StateStyle<ToggleItemState> | — | resolved per option button, 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 |
ToggleGroupItem
| Prop | Type | Default | Consequence |
|---|---|---|---|
value | string | — | the value this option presses |
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 pressed 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 ToggleGroup.tsx
Edit this page on GitHubpackages/primitives/docs/toggle-group.mdx