Button Group

Button groups present a small set of related actions with consistent spacing, predictable ordering, and wrapping behavior in narrow containers.

Component

Use fd-button-group to arrange multiple independent fd-button actions as a single visual set. The component is a layout wrapper: it does not change button semantics, it does not intercept keyboard input, and it only adds role="group" when you provide a meaningful label.

When to use

• A task needs several closely related actions — For example, "Save," "Save and continue," and "Cancel" at the end of a form or workflow step.
• You need consistent spacing and alignment — The group keeps teams from rebuilding one-off flex wrappers with inconsistent gaps and ordering.
• Actions must remain visible on narrow screens — The component wraps actions instead of hiding them in an overflow menu.

When not to use

• Don't use it for a single action — A lone button does not need a grouping wrapper.
• Don't use it when one action owns related alternates — If there is a clear primary action with a small menu of variants, use fd-split-button instead.
• Don't add label just because the buttons are adjacent — Visual proximity alone is not enough reason to create a semantic group.

Examples

Common button group patterns: default horizontal layout, spread alignment, labeled action sets, and wrapping in narrow containers. Open Storybook for the full set of alignment and direction examples. View in Storybook →

Usage

<fd-button-group>
  <fd-button variant="primary">Save</fd-button>
  <fd-button variant="outline">Save and continue</fd-button>
  <fd-button variant="subtle">Cancel</fd-button>
</fd-button-group>

With semantic grouping:

<fd-button-group label="Document actions" align="end">
  <fd-button variant="outline">Download PDF</fd-button>
  <fd-button variant="outline">Download CSV</fd-button>
  <fd-button variant="subtle">Share</fd-button>
</fd-button-group>

Properties

Name	Type	Default	Description
align	"start" | "end" | "spread"	start	Controls inline alignment for horizontal groups. spread keeps the first action at inline start and pushes the remaining actions to inline end.
direction	"horizontal" | "vertical"	horizontal	Horizontal groups stay in a wrapping row. Vertical groups always stack.
label	string	—	Adds role="group" and aria-label when the action set needs a semantic label. Omit for purely visual grouping.

Slots

Name	Description
(default)	One or more fd-button elements. Other interactive controls are technically allowed, but the documented pattern is fd-button.

CSS custom properties

Name	Default	Description
--fd-button-group-gap	var(--fdic-spacing-sm, 0.75rem)	Gap between actions in the group

Shadow parts

Name	Description
container	Internal flex container used for layout

Accessibility

• fd-button-group is presentational by default. It does not add role="group" or role="toolbar" unless you explicitly provide a label.
• When label is provided, the internal container gets role="group" plus aria-label. Use this only when the set benefits from a shared name, such as "Document actions" or "Approval actions."
• Native button semantics stay intact. Each fd-button keeps its own tab stop, focus ring, and activation behavior.
• No arrow-key interception. This is not a toolbar pattern. Users move through actions with normal Tab order.
• Wrapping preserves DOM order. Keyboard navigation and screen reader reading order remain stable when the layout changes.

Content guidelines

• Keep the main action first in DOM order. The first button should be the action you most want the user to take.
• Use align="spread" to separate the escape action from the main path. This works well for patterns like "Submit filing" on the left and "Save draft" plus "Cancel" on the right.
• Limit the number of actions. Three actions is a common maximum before decision-making slows down. If you need many actions, reconsider the workflow.
• Use explicit action labels. Government workflows benefit from direct verbs like "Save draft," "Escalate case," and "Cancel review."

Known limitations

• Toolbar behavior is out of scope in v1 — fd-button-group does not implement roving tabindex or arrow-key navigation.
• Hierarchy is documented, not enforced — The component does not prevent multiple primary buttons. Teams must apply the documented hierarchy intentionally.
• align only affects horizontal groups — Vertical groups always align actions in a single column.

Related components

• Button — Use fd-button for each action inside the group. Button groups coordinate layout; buttons retain semantics and state.
• Split Button — Use fd-split-button when one primary action owns a small set of alternate actions instead of showing several independent buttons side by side.