ButtonGroup visually merges related actions into a single cluster. It signals that the actions share context and emphasis—most often in dispatch toolbars, drawer footers, and form action rows where spacing and alignment need to read as one unit. Use it when operators should scan the actions as a set; reach for separate buttons or a SplitButton when hierarchy varies across the cluster. Leaf groups use the same track fill (--color-fill-subtle), input edge (--color-border-input), radius (--radius-control), selected wash (--alpha-12), and full-height hairline dividers between segments as SegmentedControl and ToggleGroup. The tray preserves the same total height as its members: 2.4rem for small, 2.8rem for regular, and 3.2rem for large controls.
Only leaf groups paint that tray (pr-button-group--leaf). A parent used as a layout cluster—nested ButtonGroup as a direct child, or under a shallow non-button wrapper (for example FlexBox)—drops its chrome (pr-button-group--layout) so outlines never stack. React emits exactly one of those modifiers; CSS does not re-derive the split.
Sort by
Reset zoom to 100%
When to use
Two or more actions apply to the same object or selection (save / cancel, approve / reject, edit / duplicate / delete).
The actions are peers at the same emphasis level—typically all Secondary or all SecondaryAlt.
Two logical clusters belong side by side and need a visual separator via ButtonGroupSeparator (edit cluster + share cluster).
When not to use
One action is clearly primary for the surrounding surface. Let a single Button with Primary or Critical stand on its own; grouping dilutes the primary's emphasis.
The pattern is "default action + overflow". Use SplitButton.
The actions are unrelated. Separated buttons with spacing communicate independence; a merged group lies.
The cluster would exceed a handful of actions. Move overflow into a Menu trigger.
Content guidelines
Labels stay short, title case, with active verbs; formatMessage for every string.
Avoid more than one icon-heavy button per group unless the icons are universally distinguished across the product.
Maintain parallel grammar: "Edit / Duplicate / Delete", not "Edit / Copy this / Remove permanently".
Behavior and states
Disable the whole group when the full operation is invalid; disable a single segment only when one action depends on a distinct precondition—and surface the reason.
Keyboard focus moves through each button in visual order; merged borders must not obscure the focus ring.
Best practices
Do
Keep group members at the same emphasis level. Mixing Primary and Secondary in one group is almost always wrong.
Use ButtonGroupSeparator when the group splits into sub-clusters so the border treatment communicates the grouping.
For nested groups, keep leaf clusters as direct children when you can; a single layout wrapper around a nested group is supported and the parent tray is omitted automatically.
Preserve a single primary action for the surrounding region outside the group when the hierarchy demands it.
Don't
Hide destructive actions inside a group without strong labelling. Reach for Destructive type or a confirmation step.
Cram many low-priority actions into a group to save space. Defer to Menu or Toolbar.
Place two Primary buttons side by side. The cluster stops helping the operator choose.
Accessibility
Each button keeps its own accessible name and focus treatment; the merged border is decorative. See Accessibility for the full contract.