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 inset tray, alt2 border, radius, and shared dividers as SegmentedControl and ToggleGroup. Dividers remain visible between adjacent secondary actions and between ButtonGroupText and a neighboring secondary action in either orientation. 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.
- 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).
- 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.
- 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".
- 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.
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.
Each button keeps its own accessible name and focus treatment; the merged border is decorative. See Accessibility for the full contract.
- Button for type and label rules.
- Split button for primary-plus-menu patterns.
- Toolbar for floating icon-action strips.
- Modal for confirmation framing inside a dialog.
