i

Button group

Doing · researched

Several related buttons laid out together with consistent spacing, stacked or in a row.

molecule · Carbon: ButtonSet · also called Button set, Action set · contains button

Carbon calls it a button set; "Button group" is used by five other systems.

Each block is the real component from that system’s own package, in an isolated frame. They are live: hover, focus and press them. Frames are drawn on white so systems compare on one ground, and a font a system licenses only for its own site (GOV.UK’s Transport) falls back to what the system itself specifies.

Ant Design

Space.Compact (Button.Group is deprecated) variant native: partly antd 6.6.5
Variants
—
Sizes
large, medium, small
States documented
—
Accessibility guidance
no

Index mapped only Button.Group, which is deprecated in source (warns to use Space.Compact) and shown only as a debug demo on the Button page. The supported way to join buttons is Space.Compact (div wrapper around native buttons), also horizontal/vertical via orientation.

1 corrected on re-read
  • builds_on_native: "no" → "partly" Space.Compact renders div.ant-space-compact wrapping native <button type=button>; no role on wrapper

docs ↗ · code ↗

Carbon

ButtonSet native: no @carbon/react 1.117.0
Variants
horizontal, stacked, fluid
Sizes
—
States documented
—
Accessibility guidance
yes

React ButtonSet renders a div around Button children; props stacked and fluid. Docs cover it only as 'button group' guidance inside the Button page. Index also placed ActionSet (an unpublished, not-exported-from-index.ts layout helper); it is not the public answer.

3 corrected on re-read
  • builds_on_native: "partly" → "no" ButtonSet renders a plain div (no role) wrapping native button children; rendered markup checked
  • variants: null → ["horizontal","stacked","fluid"] Docs headings: horizontally arranged, vertically stacked, fluid button groups; props stacked, fluid
  • urls: {"docs_url":"https://carbondesignsystem.com/components/button/usage/","code_url":"https://github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/ButtonSet"} → {"docs_url":"https://www.carbondesignsystem.com/building-blocks/core/components/button/guidelines","code_url":"https://github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/ButtonSet"} docs 200 after redirect to https://www.carbondesignsystem.com/building-blocks/core/components/button/guidelines; code URL 200

docs ↗ · code ↗

GOV.UK

Button group (section of the Button page) native: no govuk-frontend 6.5.1
Variants
—
Sizes
—
States documented
—
Accessibility guidance
no

A CSS object (govuk-button-group) documented under 'Grouping buttons' on the Button page; no macro or component directory of its own. Spaces buttons and links in a row or stacked on small screens. Agrees with index on the entry, but it is a layout object, not a standalone component.

2 corrected on re-read
  • alias_kind: "subset" → "same" Documented under heading "Grouping buttons" on Button page; govuk-button-group wrapper does the whole canonical job
  • builds_on_native: "yes" → "no" Example markup: <div class="govuk-button-group"> wrapping <button>s; wrapper is a generic div, no macro

docs ↗ · code ↗

Material Web

absentMaterial Web does not ship this component. Nothing is drawn in its place.

Index missed it. Labs/gb on main only: unpublished and absent from the installed 2.5.0 package. Group is a custom element with role=toolbar via ElementInternals wrapping md-gb-button children; selection none | single | multiple, plus required and disabled. No docs page. Published labs segmented button set (see content-switcher) is the other grouped-button item.

2 corrected on re-read
  • present: "ships" → "absent" labs-only: Absent as shipped: only labs/gb buttongroup (md-gb-button-group, role=toolbar, selection none|single|multiple) on main, unpublished, not in 2.5.0 and
  • urls: {"docs_url":null,"code_url":"https://github.com/material-components/material-web/tree/main/labs/gb/components/buttongroup"} → {"docs_url":null,"code_url":null} no URLs for absent rows; repo tree API 1808 entries, not truncated

· code ↗

Primer

ButtonGroup native: no @primer/react 38.40.1
Variants
—
Sizes
small, medium
States documented
—
Accessibility guidance
yes

Primer React. Renders a div wrapping each child Button in a div; role=toolbar optional (adds roving focus). Status ready.

2 corrected on re-read
  • builds_on_native: "partly" → "no" Own markup is div (BaseComponent=div) wrapping each child in a div; role only if passed. Children are native buttons
  • sizes: null → ["small","medium"] Docs: "ButtonGroups only support medium (default) and small Button sizes"

docs ↗ · code ↗

Spectrum

Button group native: partly @spectrum-web-components/button 1.12.4
Variants
—
Sizes
S, M, L, XL
States documented
default, hover, active, focus, disabled
Accessibility guidance
yes

Docs from the rsp page and swc page (spectrum.adobe.com/web/swc/components/button-group); sizes from the rsp ButtonGroup.json; orientation and align are options, not variants. Native: S2 ButtonGroup renders a div around real Button elements, and SWC 1st-gen sp-button-group is a slot. Installed SWC 1.12.4 has @spectrum-web-components/button-group. Index also placed Action group (S2/v3/SWC action-group, a toolbar of action buttons) and Toggle button group (S2 only) here; both are fair variants.

docs ↗ · code ↗

USWDS

Button group native: yes @uswds/uswds 3.14.0
Variants
default, segmented (usa-button-group--segmented)
Sizes
—
States documented
default
Accessibility guidance
yes

Agrees with index. Markup is ul/li wrapping usa-button elements (button or a); docs have an Accessibility guidance section (role=group/toolbar when not a list).

docs ↗ · code ↗

Platform facts

Native elementnone (button elements in a container)No HTML element or ARIA role is defined for a button group. APG Toolbar: 'a container for grouping a set of controls, such as buttons, menubuttons, or checkboxes'; 'Use toolbar as a grouping element only if the group contains 3 or more controls'. MDN lists the menu element as a toolbar-style list of commands (spec: 'a semantic alternative to ul to express an unordered list of commands'). MDN group role (role=group) exists for a generic grouping. Which of these a design-system button group should use is not stated by any source.
Baseline—
APG patterntoolbar
ARIA role—
Shipped by6 of 7 systems

Anatomy

    The seven states

    default Buttons in their resting state.
    hover Pointer-only CSS state; not defined by APG or HTML.
    focus Native button is focusable and takes the browser focus ring.
    active Pressed state while the pointer or key is down; CSS :active. Not defined by APG.
    disabled disabled attribute on a native button. APG Button: when the action is unavailable a custom button has aria-disabled set to true.
    error n/a — Not defined; a group of buttons has no validity.
    loading n/a — Not defined by APG or HTML.

    Every cell was read twice, the second time from raw sources by a separate pass. 10 of 35 fields changed on the second read — open any “corrected” note to see what it said before.