Toggle Group
A group of toggle buttons acting as one single- or multi-select control.
@garn/ui/toggle-groupDefault
Multi-select formatting toolbar.
Appearance
Fill treatment, shared with the items via context; `outline` gives each item a bordered surface.
Ghost
ghostOutline
outlineSizing
Item height rung (--garn-control-h-*), applied to every item via context.
smmdlgSpacing
The same control rendered across garn's density modes — compact, default, and spacious.
States
Interactive states, toggled live.
<ToggleGroup>
<ToggleGroupItem value="left">Left</ToggleGroupItem>
<ToggleGroupItem value="center">Center</ToggleGroupItem>
<ToggleGroupItem value="right">Right</ToggleGroupItem>
</ToggleGroup>State
Installation
garn is copy-in — the garn CLI writes this component's source into your project, so you own and can edit it. It resolves any base files and installs the npm dependencies below for you.
npx garn-ui add toggle-group- Registry
toggle-group- Source
- toggle-group.tsx
- Deps
@radix-ui/react-toggle-groupclass-variance-authority- Registry deps
toggleutils
Import
import { ToggleGroup } from "@garn/ui/toggle-group";Props
Generated from the component's TypeScript types.
appearance- Description
- No description.
- Type
"ghost" | "outline"- Default
ghost
size- Description
- No description.
- Type
"lg" | "md" | "sm"- Default
md
Plus 288 inherited native HTML attributes.
Styling
Target these data-slots and remap these tokens to restyle without forking the component.
[data-slot="toggle-group"]| Property | Token | Tier |
|---|---|---|
itemHeight | --garn-control-h-md | semantic · air |
ring | --garn-ringbrandable | semantic |
Overview
ToggleGroup binds related toggles into one control — a segmented single-choice selector or a multi-select toolbar (text alignment, formatting marks). ToggleGroup sets type (single for a segmented pick-one, multiple for independent toggles), owns the value, and shares appearance/size to each ToggleGroupItem. Use it for a compact set of visual, button-style options; for a labelled form choice use RadioGroup (one) or Checkboxes (several), and for a single toggle use Toggle.
Guidelines
Pick single vs multiple to match the choice. single is a segmented control (exactly one active — alignment); multiple is independent toggles (bold + italic together). Choosing the wrong type confuses what selection means.
Keep it small, labelled, and even. It works for a handful of peer options shown at once; a long list belongs in a Select. Give each item an accessible name (icon-only items especially) and a consistent size/appearance across the group.
Use it for visual options, not form fields. When the choice is a labelled field in a form, RadioGroup/Checkbox communicate intent better. Preserve the roving-focus keyboard model and make the active state clear beyond color alone.
Best practices
- Set
type="single"for one-of-N,type="multiple"for many-of-N. - Set appearance/size on the group — items inherit them via context.
- Label the group, and give each item (often icon-only) an aria-label and a unique
value.
- Don't mix unrelated actions into one group.
- Don't leave the group or its icon-only items unlabeled.
- Don't use it to navigate between pages (use tabs/links).
Content guidelines
- Use short, parallel item labels, or clear icons with aria-labels (“Left / Center / Right”).
- Keep the set small and related; a long list of choices belongs in a select.
- Name the group with an aria-label that says what the toggles control.
Accessibility
- Role
group
Enforceable contracts
Label the group and each icon-only item (aria-label on the group and on each item).
when the group has no accessible name (aria-label / aria-labelledby) and its items are icon-only
Keyboard
| Tab | Move focus into the group (roving tabindex). |
| ArrowLeftArrowRightArrowUpArrowDown | Move between items in the group. |
| EnterSpace | Toggle the focused item. |
- • The group is a single tab stop with roving focus across items.
- • Label the group (aria-label / aria-labelledby) and give each icon-only item its own aria-label.
- • `type="single"` behaves like a radio set; `type="multiple"` like a set of independent toggles.
- Status
- Stable
- Version
v0.3.0- Introduced
v0.1.0
garn doesn't yet record a per-release version history. This reflects the component's current lifecycle state; full changelog entries will appear once the metadata pipeline emits a lifecycle.history field.