Forms & input
Button group
A row of attached buttons that act as one control — a segmented view switch, a formatting toolbar, a cluster of related actions. Tighter than separate buttons, lighter than tabs.
npx shadcn@latest add @orbit/button-groupOverview
Modes
Single-select for one-of choices, multi-select for independent toggles, or plain actions that each just fire.
Icon groups
Compact icon groups are the classic toolbar — alignment, text formatting, or a zoom stepper with a value in the middle. Icon-only segments are square; always give them a title or aria-label.
Sizes
sm 30px · md 34px (default) · lg 40px, with 8px end radii and a 1px shared border. Small for dense toolbars, medium by default, large for primary view switches.
Disabled
Disable the whole group or single segments. Disabled segments drop to a flat neutral treatment and are skipped by keyboard focus.
Controlled & uncontrolled
Pass defaultValue to let the group manage its own selection, or value + onValueChange to own it. Single mode works with a string, multi mode with a string array.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| mode | "single" | "multi" | "actions" | "single" | Radio-style selection, independent toggles, or plain buttons that just fire. |
| size | "sm" | "md" | "lg" | "md" | Segment height: 30 / 34 / 40px. |
| value | string | null · string[] | — | Controlled selection — a string in single mode, an array in multi mode. |
| defaultValue | string · string[] | — | Initial selection (uncontrolled). |
| onValueChange | (value) => void | — | Fires with the new selection: the picked string (single) or all pressed values (multi). |
| disabled | boolean | false | Disables every segment in the group. |
| …rest | HTMLAttributes<HTMLDivElement> | — | Forwarded to the group root, including ref and aria-label. |
| Prop | Type | Default | Description |
|---|---|---|---|
| value | string | — | Item — segment identity within the group value. Required in single/multi modes. |
| icon | ReactNode | — | Item — 15px leading glyph. With no children the segment becomes a square icon button. |
| disabled | boolean | false | Item — disables just this segment. |
| title | string | — | Item — tooltip; doubles as the aria-label for icon-only segments. |
| …rest | ButtonHTMLAttributes | — | Item — forwarded to the underlying <button>, including ref and onClick. |
Usage
Group genuinely related choices
Views of one dataset, formatting toggles for one selection — things that share context.
Mix unrelated actions
Save next to Delete next to Share isn’t a group; those are separate buttons with their own weight.
Keep it to ~2–5 segments
Past five, a segmented control gets cramped — switch to a Select or Tabs.
Use it for primary navigation
Changing the whole page is Tabs’ job; a button group stays within one view.
Keyboard & accessibility
Single and multi groups render role=group with aria-pressed toggle buttons: Tab enters the group, Left/Right arrows (and Home/End) move focus within it, Enter or Space toggles. Actions mode renders plain buttons that Tab moves between. Icon-only segments take their accessible name from title or aria-label; give the group itself an aria-label.