Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
37.6 KB
Raw Blame

schema_version: 3 template_version: 7 kind: component id: component:ButtonGroup authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-25 owners: [cixzhang] review_triggers: [public-api, behavior, layout, theming, accessibility] verified_by: [ packages/core/src/ButtonGroup/ButtonGroup.test.tsx, packages/core/src/ButtonGroup/tests/ButtonGroupCorners.interaction.browser.spec.ts, packages/core/src/Layer/layerScopedContext.test.tsx, packages/core/src/hooks/useListFocus.test.tsx, ] modules: [] families: [family:buttons] design_specs: [] architecture: [ architecture:component-size-cascade, architecture:component-theming-surface, architecture:public-component-api, ] contributing: []

system_specs: [spec:AST-038, spec:AST-085]

ButtonGroup component contract

Contract at a glance

Area Contract
Public contract None changes. ButtonGroup takes label, orientation, size, elevation, isDisabled, and Button or IconButton children.
Behavior A labelled role="group" that joins its Button members into one connected surface, gives them a default size and its disabled state, owns one shared elevation, and is one Tab stop with arrow-key roving.
End-user impact Keyboard users reach the whole group with one Tab and move through it with arrows. A disabled group without tooltips has no Tab stop, so keyboard users cannot find it or hear that it is disabled.
Builder impact None.
Compatibility/readiness No API or default change; its DOM change is listed below. Disabled members use native disabled, the Tab stop leaves disabled and busy-only members, and wrapped members lose connected geometry; all are listed under Current-state impact.
Review checks Reject a group without a name, gaps between members, rounded inner corners, a shadow on a member, more than one Tab stop, or arrows that steal keys from a member's open menu.
Governing rules family:buttons FR3, FR8, FR10–FR12, AV5; architecture:component-size-cascade INV3–INV8; spec:AST-085 FR1, FR7; spec:AST-038 FR7, FR8.

This table is a review projection; the body below is authoritative.

Intent

ButtonGroup presents a few related actions as one connected control. It owns the group's accessible name, connected geometry, shared elevation, inherited size and disabled state, and the group's single-Tab-stop keyboard model, as family:buttons assigns. Consumer usage lives in ButtonGroup.doc.mjs.

Compatibility and migration

  • Released default preserved: yes for a mouse; under the touch presentation a press gains the slide across the buttons; orientation="horizontal", size="md", elevation="none", isDisabled={false}
  • Compatibility class: no public prop, default, or export change; under the touch presentation the DOM gains the action-group item marker on each tracked button, the gesture host's data-astryx-touch-action marker on the group root and the hit layer's inset properties, and an enabled group's root is also position: relative, so absolutely positioned descendants resolve against it there
  • Controlled/uncontrolled behavior: not applicable
  • Migration decision: none

Consumer migration instructions belong in consumer docs and release notes.

Ownership boundary

Owns

  • The group root: role, accessible name, orientation and disabled exposure, and the button-group target.
  • Connected geometry its Button members paint: outer-only corners, leading-edge dividers, and no press scale.
  • One shared resting elevation, and flat members.
  • The default size and disabled state it gives its members.
  • Roving focus: one Tab stop, arrow keys, Home and End.

Does not own / non-goals

  • Each member's own surface, naming, activation, pending, and disabled rendering — owned by component:Button and component:IconButton. A press that slides across members acts on the lifted member, as family:action-groups owns.
  • A member's menu or other layer, and keys pressed inside it — owned by that member (for example component:DropdownMenu).
  • Selection state across toggles — owned by component:ToggleButtonGroup.
  • Horizontal overflow — uncontracted; the group does not wrap or collapse.
  • Nested ButtonGroups — unsupported; behavior is uncontracted.

Public concepts

Concept Closed values or states Meaning Availability by variant/orientation/state Default Owner Stability Invalid-value behavior
Orientation horizontal, vertical Direction of the row and of arrow keys. Always. horizontal component:ButtonGroup Stable TypeScript rejects other values.
Size sm, md, lg Default size for members. Always; a member's own size wins. Inherited size, else md family:buttons Stable TypeScript rejects other values.
Elevation none, low, med, high Shadow under the whole connected surface. Always; members paint none. none family:buttons Stable TypeScript rejects other values.
Disabled off, on Every Button member is disabled. Always. off component:ButtonGroup Stable Not applicable.

Behavioral and layout contract

ID Invariant Basis
FR1 The root is one element with role="group" and aria-label set to label. It reflects orientation as data-orientation, never aria-orientation, and sets aria-disabled="true" only while disabled. ref, data-testid, className, style, xstyle, and other DOM props reach it. family:buttons FR11; current source and tests
FR2 Members sit edge to edge with no gap, stretched across the cross axis: a row when horizontal, a column when vertical. family:buttons FR12; current source
FR3 Group geometry is painted by Astryx Button members; other children keep their own paint. Only the group's outer corners are rounded: the first member's leading corners and the last member's trailing corners. A trailing layer element a member renders after itself (popover, template, or dialog) does not count as a member, so the real last member keeps its rounded corners. Any other following element, including a display-contents wrapper or a raw button, counts as a member. A Button member wrapped in a Tooltip or HoverCard MUST join the connected surface like a direct member (family:buttons FR12). Implementation gap: inside that display-contents wrapper the Button is both the first and the last child, so in a group of two or more it keeps all four corners rounded wherever it sits, and draws no divider when it is not first. family:buttons FR12; current tests
FR4 Every Button member after the first draws a divider on its leading edge (inline-start when horizontal, block-start when vertical) in the border color, or in the on-accent color on a primary or destructive member; a wrapped member does not (FR3 gap). Members do not take Button's press scale. family:buttons FR12; current source
FR5 The group paints the shadow for its elevation, following the element radius. Every Button member paints no shadow and reflects data-elevation="none", whatever its own elevation says. family:buttons FR8, FR10; current tests
FR6 The group provides its resolved size to descendants up to the next layer boundary (spec:AST-038 FR7, FR8): an explicit size, then the nearest outer provider, then md. A member's own size wins. architecture:component-size-cascade INV3–INV8; current source; spec:AST-038 FR7
FR7 While disabled, every Button member MUST be disabled under component:Button FR10: focusable with aria-disabled, inert, and never running its action, so the group keeps its Tab stop (spec:AST-085 FR1, FR7). Implementation gap: members without a tooltip render native disabled, so a disabled group contributes no Tab stop. family:buttons FR3; spec:AST-085 FR7; current tests
FR8 The group is one Tab stop. The stop starts on the first enabled member and moves with arrow navigation. A link member counts as a member. The stop MUST always sit on exactly one member, and a member that becomes busy or disabled MUST keep it (component:Button FR9, FR10; spec:AST-085 FR1, FR7). Implementation gap: the group repairs the stop only after its own renders and when focus enters a member, and each repair keeps an enabled holder or gives the stop to the first enabled member. Between repairs the stop can sit on a member that has become busy-only, disabled, or unmounted, so the group can have a second stop or none; focus that arrives by pointer or by code does not take the stop, so the next Tab or Shift+Tab can stop inside the group; and a fully disabled group repairs nothing, so a group disabled from its first render gives each tooltip-bearing member its own stop and native-disabled members none. family:buttons AV5; WAI-ARIA APG roving tabindex; current tests
FR9 Horizontal groups move with Left and Right in visual order, reversed under RTL; vertical groups move with Up and Down. Home and End jump to the first and last enabled member. Movement wraps at the ends. family:buttons AV5; current tests
FR10 Keys pressed inside a member's open layer (such as a DropdownMenu) belong to that layer, and the group keeps its Tab stop on its own members. A group inside a popover or other layer still handles its own arrow keys. The group's context does not reach Buttons rendered inside a member's layer (spec:AST-038 FR7). Current source and tests; spec:AST-038 FR7
FR11 The root carries astryx-button-group and reflects data-size, data-orientation, and data-elevation. family:buttons FR10; architecture:component-theming-surface; tests

Allowed variation

  • AV1 — Members. Button, IconButton, and a Button-triggered DropdownMenu are supported members; variants may differ between members.
  • AV2 — Theme paint. Themes may restyle the group and member surfaces through button-group and button without changing connected geometry.

Representative states

State Required invariant Allowed variation
Horizontal, at rest Named group; one Tab stop on the first member; outer corners only. Member variants.
Vertical Column; Up and Down move focus; block-start dividers. —
Elevated Shadow on the group; members flat. Tier.
Trailing DropdownMenu The menu trigger keeps rounded trailing corners; arrows inside the open menu stay with it. Menu content.
One member disabled Implementation gap: the Tab stop leaves it when the group repairs (FR8). Tooltip present or not.
Group disabled aria-disabled on the group; every member focusable and inert; one Tab stop. Implementation gap: native-disabled members give no Tab stop; disabled from the first render, tooltip-bearing members are one stop each (FR7, FR8). —

Transformation and precedence order

  • ORD1 — Member size. Member size, then the group's resolved size.
  • ORD2 — Member elevation. Inside a group, always none; the group's elevation paints.
  • ORD3 — Member availability. A member is disabled when the group or the member is disabled; neither can re-enable the other. Otherwise Button's own availability rules apply.

Performance and resources

  • PR1 — Tab-stop repair. The group repairs the Tab stop after each of its own renders and when focus enters a member; it adds no global listener beyond the press tracking family:action-groups FR5 gives it.

Accessibility contract

  • AR1 — Group name. The group exposes role="group" and its label as its accessible name; members keep their own names (family:buttons FR11).
  • AR2 — Keyboard. FR8–FR10 are the keyboard contract.
  • AR3 — Disabled exposure. A disabled group exposes aria-disabled on the group; members expose disabled per component:Button AR5 (FR7 gap).
  • AR4 — Focus indicator. Each member paints Button's focus indicator.

Design relationships

Anatomy or state Design requirement Representation authority Hierarchy role Component contract
Button Members joined into one surface with outer-only corners. Current source and tests Prominent FR2, FR3
Divider Thin leading-edge border between members; on-accent on solid members. Current source Supporting FR4
Group shadow One shadow under the connected surface. Current source and tests Supporting FR5

No design record governs ButtonGroup. The root carries the button-group target; the Button and Divider anatomy parts are painted by each member's button target. The consumer anatomy names no root part, so this record carries no anatomy-theming map.

Family and system relationships

  • family:buttons assigns ButtonGroup connected geometry, roving focus, inherited size and disabled state, and one shared elevation (FR8, FR11, FR12); ButtonGroup adopts them.
  • component:Button paints the connected geometry from the group's context and owns each member's behavior.
  • architecture:component-size-cascade owns size inheritance (FR6).
  • spec:AST-085 FR7 applies to group disablement; the gap is FR7 here.

Verification map

Contract Verification Representative states Mutation or failure expectation Audit section
FR1, AR1 ButtonGroup.test.tsx role, label, ref, data-testid, orientation Horizontal and vertical A missing name, aria-orientation, a dropped ref, or a dropped data-testid fails. Evidence gap: no test passes className, style, or xstyle. audit:ButtonGroup/accessibility
FR3 ButtonGroupCorners.interaction.browser.spec.ts in the Chromium interaction lane; ButtonGroup.test.tsx trailing-radius suite (compiled selector shape and membership; jsdom never receives the rule) Two members, horizontal and vertical; popover, template and dialog pieces after members, up to seven; a member between popovers; display-contents wrapper, Tooltip-wrapped and raw-button followers; tooltip'd and DropdownMenu trailing members; an InputGroup button addon last and first A square trailing member, or a rounded inner member, fails; a compiled trailing selector that uses :last-child or a sibling-relative :has() fails. Evidence gap: the jsdom suite and the browser story render wrapped members only last and check the member before them; no test checks a wrapped member's own corners or divider in any position. audit:ButtonGroup/layout
FR5, FR11 ButtonGroup.test.tsx elevation suite Every tier; member with its own elevation Identical classes for two tiers, a mismatched data-elevation, or a member not reporting none fails. audit:ButtonGroup/theming
FR11 (target, size) Evidence gap: no test asserts astryx-button-group or data-size on the root Each size — audit:ButtonGroup/theming
FR7, AR3 ButtonGroup.test.tsx disabled cases Group disabled An operable member fails. Native-disabled and no-Tab-stop assertions match the FR7 gap. audit:ButtonGroup/accessibility
FR8, AR2 ButtonGroup.test.tsx roving-tabindex suite Enter and leave; disabled member; unmount; becomes disabled; link Two Tab stops or a lost stop fails. The suite asserts that a disabled member never holds the stop and that the stop is repaired away from it, matching the FR8 gap. Evidence gap: no test of a busy or self-unmounted holder, pointer focus, or a group disabled after mount. audit:ButtonGroup/accessibility
FR9, FR10, AR2 ButtonGroup.test.tsx keyboard-navigation suite; useListFocus.test.tsx "useListFocus disabled-item skipping" for Home and End, which reach enabled ends; layerScopedContext.test.tsx "ends group-owned disabled state while preserving explicit and inner-group state" for the layer boundary Arrows, Home, End, vertical, RTL, open menu, group inside a popover Wrong direction, no wrap, Home or End landing on a disabled member, stealing a menu's keys, or group state leaking into a member's layer fails. audit:ButtonGroup/accessibility
FR2, FR3, FR4, FR6 Evidence gap: no assertion of gap-free layout, divider paint, the absent press scale, non-Button children keeping their own paint, or member size inheritance beyond rendering — — audit:ButtonGroup/layout
ORD2 ButtonGroup.test.tsx elevation suite Member with its own elevation A member not reporting none fails. audit:ButtonGroup/theming
ORD1, ORD3, PR1, AR4 Evidence gap: no test asserts member size precedence, a member isDisabled inside an enabled group, when the Tab stop is repaired, or the member focus indicator — — audit:ButtonGroup/behavior

Current-state impact

  • Disabled focusability (FR7, AR3). A disabled group renders its members with native disabled, so the group has no Tab stop, against spec:AST-085 FR1 and FR7 and family:buttons FR3. The group's tests assert that state.
  • Tab stop (FR8). The Tab stop leaves a disabled or busy-only member when the group repairs it; between repairs the group can have a second stop or none, including after a pointer click on a member or when the holder unmounts or disables itself; and a group disabled from its first render gives each tooltip-bearing member its own stop, against spec:AST-085 FR1 and FR7.
  • Wrapped members (FR3, FR4). A Button wrapped in a Tooltip or HoverCard keeps four rounded corners in any position, and no divider when it is not first, against family:buttons FR12.

Decision log

No component-local decision. ButtonGroup applies family:buttons.

Open questions

None.

Content boundary

This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or family/system rules. It links to their owners.