Button Group

OverviewCopy Anchor Link

A button group takes two or more buttons that share a purpose and binds them into one control. The inner corners square off, adjacent borders overlap into a single hairline, and the whole thing reads as a connected toolbar segment rather than a row of loose chips.

There are two jobs it does well:

• Single-select — a small set of mutually exclusive options where one is always active (a view switcher, a date range, a sort order). The selected button stays visibly pressed.
• Action cluster — a handful of related, independent commands sitting side by side (zoom in / reset / out, undo / redo, alignment).

When to useCopy Anchor Link

• To switch between 2–5 mutually exclusive views or modes (List / Board / Calendar)
• To group tightly related commands in a toolbar (– / 100% / +)
• For pagination and stepper controls (Prev / 1 / 2 / 3 / Next)

When not to useCopy Anchor Link

• For a styled, track-backed single-select with a sliding indicator — use a segmented control instead. A button group is the squarer, more utilitarian sibling.
• For one standalone action — use a plain button.
• When the options need to wrap to multiple lines or carry long labels — use stacked buttons or a list. A group is meant to stay on one line.
• For navigation between unrelated pages — use links or a tab bar.

AnatomyCopy Anchor Link

A button group is a flex container (.nm-button-group) wrapping ordinary .nm-button elements. The group does no styling of its own beyond layout — it overlaps each button's leading edge by -1px so shared borders never double up, then strips the inner corners so only the two end caps stay rounded.

What each part is driven byCopy Anchor Link

Square & pillCopy Anchor Link

Two end-cap shapes. The default squares the inner corners and keeps the outer corners at the button's own radius. Add .nm-button-group--pill to round the two end caps into a fully capsule-shaped control.

Square (default)Copy Anchor Link

PillCopy Anchor Link

Pill end caps read softer — reach for them on filter bars and date pickers; keep square for dense editing toolbars.

Single-selectCopy Anchor Link

The most common use: a set of mutually exclusive options where exactly one is active at all times. Mark the active button with aria-pressed="true" (or add .is-selected) — the selection styling is wired for secondary buttons, which is the intent a group should almost always use.

Exactly one button carries aria-pressed="true". Selection is a state of the group, not of any single button.

• Keep one — and only one — option selected at all times. A single-select group has no empty state.
• Use secondary intent so the unselected buttons stay quiet and the active one reads clearly against them.
• Order options the way a user thinks about them (chronological, small→large), not alphabetically.

Action groupsCopy Anchor Link

When the buttons are independent commands rather than a single choice, drop the pressed state — every button is just a regular button that happens to be joined to its neighbours. Use this for steppers, paging, and command clusters.

StepperCopy Anchor Link

PaginationCopy Anchor Link

Undo / redoCopy Anchor Link

SizesCopy Anchor Link

A group inherits its height, padding, font size, and corner radius from the nm-button--{size} class on its children — there is no separate group size. Use the same size on every button in a group; mixing sizes breaks the shared border. The five steps mirror the button scale.

Choosing a sizeCopy Anchor Link

• xs / sm — dense toolbars, table headers, filter rows
• md — default for panels, cards, page-level view switchers
• lg / xl — marketing surfaces, touch-first kiosks, signing screens

Icon groupsCopy Anchor Link

Buttons in a group take the same icon options as standalone buttons: leading icon, trailing icon, or icon-only. Icon-only groups are the workhorse of editing toolbars — keep them to universally understood glyphs and give every button an aria-label.

Icon-only group · md · every button labelled. Match the icon weight across the group so the row reads evenly.

Icon + labelCopy Anchor Link

StatesCopy Anchor Link

Each button in a group keeps its own interaction states. The group adds one rule: a hovered, focused, or active button is lifted with z-index:1 so its full border paints cleanly over the overlapped neighbours — no broken seams.

Secondary · md · default, hover, selected, and active within one group.

Selected vs. activeCopy Anchor Link

• Selected (aria-pressed="true" / .is-selected) is a persistent state — the option the user has chosen. It survives focus moving elsewhere.
• Active is the momentary press while the pointer is down. Don't conflate them: a single-select group shows exactly one selected button, and any button can be active for the instant it's clicked.

FocusCopy Anchor Link

Focus uses the button's own :focus-visible ring. Inside a group the focused button lifts above its neighbours so the full ring is visible on every side. Never suppress it.

No disabled stateCopy Anchor Link

Like buttons, groups don't ship a disabled appearance. If an option isn't available, leave the rest of the group enabled and explain the constraint inline rather than greying a segment out.

Light & dark themeCopy Anchor Link

Groups inherit every colour from the button tokens, so they remap automatically under data-theme. Fill, selected state, border, and focus ring all adapt — author once.

Both previews are locked to their theme — toggle the page theme to see the rest of the docs cascade.

Groups in contextCopy Anchor Link

Where button groups earn their keep. These are layout recommendations, not rigid rules.

List header — view switcherCopy Anchor Link

A quiet secondary group for switching the view, a single loud accent button for the primary action. Don't let the group compete with it.

Filter bar — date rangeCopy Anchor Link

Editor toolbarCopy Anchor Link

Break a long toolbar into several short groups by function. The gaps between groups do the visual grouping for you.

Do & don'tCopy Anchor Link

The rules that keep a group reading as one clean control.

AccessibilityCopy Anchor Link

A button group is a layout wrapper — semantics live on the buttons and on the role you give the container.

Choosing a roleCopy Anchor Link

• Single-select (mutually exclusive, one always active): wrap in role="group" with an aria-label, and mark each button with aria-pressed="true|false". For a stricter radio-style relationship, use role="radiogroup" on the container and role="radio" + aria-checked on the buttons.
• Action cluster (independent commands): use role="group" with an aria-label that names the cluster ("Pagination", "Text formatting"). Each button stays a normal <button type="button">.

KeyboardCopy Anchor Link

• Tab moves into the group and Tab moves out — every button is individually focusable by default.
• Space and Enter trigger the focused button.
• For role="radiogroup", manage arrow-key roving focus so the group is a single Tab stop, per the WAI-ARIA radio pattern.

LabelingCopy Anchor Link

• Always give the container an aria-label (or aria-labelledby) so assistive tech announces what the group controls.
• Icon-only buttons each require their own aria-label describing the action, not the glyph ("Align left", not "left icon").
• Reflect selection with aria-pressed (toggle buttons) or aria-checked (radio pattern) — never rely on the fill colour alone.

ContrastCopy Anchor Link

• Selected and unselected segments both meet WCAG 2.2 AA for label-over-fill in light and dark themes.
• The focus ring keeps ≥ 3:1 contrast against the button and the page, and lifts above neighbours so it's never clipped.

PlaygroundCopy Anchor Link

Click a segment to select it. The markup updates live — copy it straight into your product.

Token referenceCopy Anchor Link

A button group has no colour tokens of its own — every fill, border, and selected state resolves through the button tokens. The group layer only owns layout and corner behaviour.

Inherited from buttonCopy Anchor Link

Group-layer behaviour (no custom properties)Copy Anchor Link

Geometry comes entirely from the nm-button--{size} class on the children — there's nothing to override on the group itself.

ImplementationCopy Anchor Link

Wrap a row of nm-button elements in .nm-button-group. No JavaScript is required for layout; you only wire up click handling and the aria-pressed toggle for single-select behaviour.

<link rel="stylesheet" href="namirial-theme.css">

<div class="nm-button-group" role="group" aria-label="View">
  <button class="nm-button nm-button--secondary nm-button--md" aria-pressed="true">List</button>
  <button class="nm-button nm-button--secondary nm-button--md" aria-pressed="false">Board</button>
  <button class="nm-button nm-button--secondary nm-button--md" aria-pressed="false">Calendar</button>
</div>

CSS classesCopy Anchor Link