ButtonGroup

Usage

ButtonGroup is the DS molecule for a row of related actions: it wraps the buttons in role="group" semantics with a required accessible name, composes the Button atom (variants, sizes, loading, disabled, 44px tap floor), and wraps responsively on narrow viewports. Use it instead of a hand-rolled flex gap-2 div of Buttons — the group semantics and label are the point.

import { ButtonGroup, Button } from '@epasslive/design-system'

// Declarative items mode
<ButtonGroup
  ariaLabel="Quick actions"
  items={[
    { id: 'pdf', label: 'Download PDF', variant: 'primary', onClick: downloadPdf },
    { id: 'wallet', label: 'Add to Apple Wallet', variant: 'secondary' },
    { id: 'share', label: 'Share link', variant: 'ghost' },
  ]}
/>

// Slot mode — caller-provided children
<ButtonGroup ariaLabel="Edit actions">
  <Button variant="secondary" size="sm">Cancel</Button>
  <Button size="sm">Save</Button>
</ButtonGroup>

// Permission-gated item — hidden is omitted from the DOM entirely
<ButtonGroup
  ariaLabel="Admin actions"
  items={[
    { id: 'edit', label: 'Edit', variant: 'primary' },
    { id: 'delete', label: 'Delete', variant: 'danger', hidden: !canDelete },
    { id: 'export', label: 'Export CSV', variant: 'secondary' },
  ]}
/>

Two modes, one contract

• items mode — declarative: one source-of-truth array, Button atoms rendered in order, per-item variant/size/loading/disabled/icon/hidden. Best for action clusters driven by data or permissions.
• slot mode (children) — wrap your own Buttons (or mixed controls, e.g. <Select> + Buttons) in the group semantics. Best for form footers where buttons carry non-declarative props (type="submit", refs).
• mutual exclusivity — when both items and children are given, items wins.

Alignment

align="end" applies ml-auto to the group container — it only works when the parent is a flex container (the auto margin then pushes the group to the end of the main axis). Inside a block-level parent the ml-auto is inert and the group stays left-aligned. All current align="end" consumers sit in flex/toolbar parents.

Props

ButtonGroupItem

Fields of each entry in the items array (items mode):

Accessibility

• Container renders role="group" with an aria-label — the ariaLabel prop is required by the type system (WAI-ARIA 1.2: a group must be named).
• Natural Tab order — every button is individually tabbable. This is the WAI-ARIA group pattern, not a toolbar: arrow-key roving belongs to toolbar/segmented patterns (see the dedicated TableToolbar / TextFormatToolbar molecules).
• hidden items are omitted from the DOM entirely — not visually clipped and not aria-hidden — so neither Tab nor screen readers ever encounter them (WCAG 2.1.1).
• Per-item ariaLabel overrides the accessible name when the visible label needs more context; leading icons are aria-hidden decoration.
• Focus-visible ring (2px teal) and the 44px tap floor are inherited from the Button atom (WCAG 2.4.7 / 2.5.5).