UX Patterns Guide
UI + UX Selection And Choice established

Button group

Group only related action buttons, name the group when needed, define one local scope, establish clear emphasis order, explain unavailable commands, preserve responsive order, and separate high-risk commands from safe navigation or submission actions.

Open in lab Compare alternatives
Decision first

Choose this pattern when the problem matches

Use when

  • A form, dialog, panel, card, or workflow footer needs two to four related visible commands.
  • Users need to compare primary, secondary, cancel, back, reset, skip, apply, or export commands in the same task context.
  • The commands are frequent or important enough to stay visible instead of hiding behind a menu.

Avoid when

  • The controls are mutually exclusive view modes that need a selected state.
  • The commands are unrelated, numerous, or low priority enough to require an action menu or toolbar overflow.
  • The controls navigate between destinations rather than executing commands.
  • A single primary action is enough and alternatives would add hesitation.
  • The group would place a destructive command beside safe progress without meaningful separation or review.

Problem it prevents

Users need to choose between a few related commands in one workflow moment, but loose button rows can imply false relationships, create competing primary actions, hide blocked states, and place destructive commands too close to safe progress.

Pattern anatomy

What a strong implementation has to make clear

User need

A form, dialog, card, toolbar section, panel footer, wizard step, or result area has multiple commands that belong to one local task.

Pattern promise

Group only related action buttons, name the group when needed, define one local scope, establish clear emphasis order, explain unavailable commands, preserve responsive order, and separate high-risk commands from safe navigation or submission actions.

Required state

Default group with a clear label or surrounding context.

Recovery path

Users hesitate because Save, Submit, Continue, and Next are all high-emphasis buttons in the same group.

Access contract

Use native button elements for actions so Enter and Space activation, disabled behavior, and focus work predictably.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • A form footer shows Save draft, Continue, and Cancel as one named action group, with Continue primary only after required work is saved.
  • A filter panel footer groups Apply filters and Reset filters while keeping Export outside the submit path.
  • A user saves a draft, sees Continue become available, then continues without losing the saved status or action hierarchy.
  • A user chooses Reset changes from a separated danger action and receives a clear reset result instead of accidentally resetting beside Continue.
Weak implementation

Vague, hidden, hard to recover from

  • A footer contains Save, Continue, Delete, Help, View report, and Open settings as identical primary buttons.
  • A mobile button row turns actions into unlabeled icons and reorders Cancel before Continue without explanation.
  • A disabled Continue button gives no reason, so the user repeatedly presses Save, Cancel, and Back to find a path forward.
  • A destructive Delete button sits beside Continue with the same emphasis and no review, causing input mistakes.
UI guidance
  • Render a small group of visibly related action buttons with one clear scope, one dominant primary action when needed, lower-emphasis alternatives, consistent labels, visible focus, and stable spacing.
  • Keep the group readable across narrow screens by stacking deliberately, preserving source order, keeping hit targets intact, and separating destructive or risky actions from safe forward movement.
UX guidance
  • Use a button group when users need to choose between a few related commands at the same workflow moment, such as saving, continuing, going back, cancelling, applying, resetting, or exporting in one local task.
  • Make hierarchy, availability, result feedback, and risk clear before activation so users do not have to guess which action is recommended or why a command is unavailable.
Implementation contract

What the implementation must handle

States

  • Default group with a clear label or surrounding context.
  • Primary, secondary, tertiary, and danger visual hierarchy when those roles are present.
  • Focused state for each button in source order.
  • Hover or pressed state for pointer and touch feedback.

Interaction

  • Each button performs a command immediately or starts a named flow; buttons in the group do not represent persistent selected values unless the component is intentionally a segmented or toggle group.
  • The group has one local scope and a programmatic grouping when surrounding context is insufficient.
  • Button labels use verbs and objects that match the result message, accessible name, and logged action.
  • The primary action is visually dominant only when it is the recommended next action.

Accessibility

  • Use native button elements for actions so Enter and Space activation, disabled behavior, and focus work predictably.
  • Use role group, a list, or role toolbar only when the grouping relationship or toolbar behavior is meaningful.
  • Give the group an accessible name when surrounding text does not explain the shared scope.
  • Do not use aria-pressed for ordinary command buttons; reserve it for toggle buttons whose label remains stable.

Review

  • Do all buttons in the group share one local task scope and workflow moment?
  • Is the recommended action visually clear without creating two competing primary commands?
  • Can users tell why an unavailable command is blocked and what fixes it?
  • Are destructive commands separated from safe progression and backed by confirmation, undo, or recovery?
Interactive lab

Inspect the states before you copy the pattern

Choose related task actions

Save the draft to unlock Continue, run Continue, trigger Reset changes, restore the group, and compare the disabled reason with the bad mixed-action row.

Button group
Interactive demo is ready

Launch the live UI/UX lab when you want to inspect states, keyboard behavior, and common failure modes.

State To Inspect

Default group with a clear label or surrounding context.

Keyboard / Access

Tab moves to each enabled button in source order unless the group is intentionally implemented as a toolbar with toolbar keyboard behavior.

Avoid Generating

Putting unrelated actions into one row because the layout has space.
Evidence trail

Source-backed claims behind this guidance

U.S. Web Design System Button group

U.S. Web Design System - checked

USWDS documents button groups for related actions, Back and Continue flows, group semantics, responsive stacking, and cautions against unrelated or destructive action mixing.

Carbon Design System Button

IBM Carbon Design System - checked

Carbon documents button hierarchy, related calls to action, primary and secondary placement, group combinations, stacked button groups, and icon consistency.

WAI-ARIA Authoring Practices Guide

W3C Web Accessibility Initiative - checked

APG button guidance distinguishes command buttons from toggle buttons with aria-pressed and documents disabled action state.

Material Design Buttons

Google Material Design - checked

Material documents button variants, icon and text combinations, and common button treatments used in grouped action contexts.

Full agent/debug reference

Problem Context

  • A form, dialog, card, toolbar section, panel footer, wizard step, or result area has multiple commands that belong to one local task.
  • Users must distinguish the recommended next action from alternatives such as save draft, cancel, back, skip, reset, export, or delete.
  • The actions are visible commands, not selected values, view modes, or hidden menu items.
  • The group must survive mobile stacking, high zoom, keyboard focus, processing states, and disabled dependencies without losing action meaning.

Selection Rules

  • Choose a button group when two to four actions are contextually related and should be considered together at one workflow moment.
  • Use a segmented control when the buttons represent mutually exclusive modes or views and need a persistent selected state.
  • Use a menu button when secondary commands are numerous, lower priority, or contextual enough to hide behind a named trigger.
  • Use confirmation dialog after a clearly labelled dangerous action is chosen and the consequence needs review before commitment.
  • Use text links or navigation patterns when the controls are destinations rather than commands.
  • Avoid placing destructive actions directly beside safe forward actions unless visual separation, wording, confirmation, or undo makes the risk clear.
  • Keep one primary action unless the workflow intentionally presents equal choices with no recommended path.
  • Move low-frequency or unrelated commands out of the group rather than adding more buttons to a crowded row.

Required States

  • Default group with a clear label or surrounding context.
  • Primary, secondary, tertiary, and danger visual hierarchy when those roles are present.
  • Focused state for each button in source order.
  • Hover or pressed state for pointer and touch feedback.
  • Disabled or unavailable state with visible reason.
  • Processing state after activation that prevents duplicate submission.
  • Successful action status that names the command that ran.
  • Responsive stacked state preserving action order and readable labels.
  • Separated destructive action state.
  • Long label and high-zoom state without clipped text.

Interaction Contract

  • Each button performs a command immediately or starts a named flow; buttons in the group do not represent persistent selected values unless the component is intentionally a segmented or toggle group.
  • The group has one local scope and a programmatic grouping when surrounding context is insufficient.
  • Button labels use verbs and objects that match the result message, accessible name, and logged action.
  • The primary action is visually dominant only when it is the recommended next action.
  • Disabled commands are either temporarily blocked with a reason or removed until relevant.
  • Processing actions prevent duplicate activation and announce progress or completion.
  • Destructive actions are visually separated, lower-emphasis unless explicitly primary, and routed to confirmation, undo, or clear recovery when needed.
  • Keyboard users tab through buttons in the same order that visual layout implies; Enter and Space activate the focused button.
  • Responsive stacking keeps safe progression, cancellation, and danger relationships understandable.

Implementation Checklist

  • Inventory each command and remove actions that do not share the same local task scope.
  • Choose the primary action and make secondary alternatives lower emphasis.
  • Place danger actions away from safe forward actions or put them behind confirmation or undo.
  • Use real button elements for commands and reserve links for navigation.
  • Wrap the group in a list, role group, or toolbar only when that grouping communicates the relationship accurately.
  • Keep visible labels, accessible names, icons, and result status aligned.
  • Explain disabled states through helper text, inline status, or dependency messaging.
  • Prevent duplicate activation during processing and restore the button state after completion or error.
  • Test source order, mobile stacking, high zoom, forced colors, focus rings, touch targets, and localization.

Common Generated-UI Mistakes

  • Putting unrelated actions into one row because the layout has space.
  • Using two or more high-emphasis buttons that compete for the same next step.
  • Mixing destructive and non-destructive actions with identical visual weight.
  • Using button groups as page navigation or content links.
  • Giving command buttons aria-pressed selected state when they are not toggles or modes.
  • Disabling the primary button without explaining the unmet condition.
  • Replacing text labels with icons at small widths.
  • Letting responsive wrapping reorder actions unpredictably.

Critique Questions

  • Do all buttons in the group share one local task scope and workflow moment?
  • Is the recommended action visually clear without creating two competing primary commands?
  • Can users tell why an unavailable command is blocked and what fixes it?
  • Are destructive commands separated from safe progression and backed by confirmation, undo, or recovery?
  • Will source order, visible order, and keyboard order remain understandable on mobile and at high zoom?
Accessibility
  • Use native button elements for actions so Enter and Space activation, disabled behavior, and focus work predictably.
  • Use role group, a list, or role toolbar only when the grouping relationship or toolbar behavior is meaningful.
  • Give the group an accessible name when surrounding text does not explain the shared scope.
  • Do not use aria-pressed for ordinary command buttons; reserve it for toggle buttons whose label remains stable.
  • Keep disabled reasons and processing status available to screen reader users through nearby text or live regions.
  • Maintain visible focus, sufficient contrast between emphasis levels, and full labels at high zoom.
  • When icons appear in grouped buttons, use them consistently and keep text labels or precise accessible names.
Keyboard Behavior
  • Tab moves to each enabled button in source order unless the group is intentionally implemented as a toolbar with toolbar keyboard behavior.
  • Enter or Space activates the focused command button.
  • Disabled buttons cannot be activated and their blocked reason is discoverable nearby.
  • After activation, focus stays on the button, moves to the next workflow step, or lands on confirmation or status according to the command result.
  • During processing, duplicate activation is blocked and completion or failure is announced.
  • Responsive stacking does not change the logical focus order unexpectedly.
Variants
  • Form footer action group
  • Dialog action group
  • Wizard back and continue group
  • Panel apply and reset group
  • Card action group
  • Toolbar action cluster
  • Stacked mobile button group
  • Danger-separated button group
  • Processing button group

Verification

Last verified: