Button group

A ButtonGroup wraps two or more <Button> (or <IconButton>) elements into a connected cluster. Use it when the buttons are siblings in the same decision — the surrounding container makes the grouping explicit.

Use it for

• Save / Cancel pairs in dialogs and form footers
• Confirm / Discard pairs in destructive flows
• Sign up / Log in stacks on auth screens
• Toolbar action clusters where buttons act together

Import

import { ButtonGroup, Button } from '@brikdesigns/bds';

Variants

Horizontal

Vertical

Stack buttons in a column. Pair with fullWidth on each button for stacked auth screens.

Full width

fullWidth on the group stretches each child equally. Use in narrow contexts (sheets, sidebars).

When not to use

• Don't put more than 3 buttons in a group. A "toolbar" of 5 unrelated actions is a different pattern — use spacing, not grouping.
• Don't mix sizes inside a group. All buttons should share the same size. Mixed sizes break the rhythm.
• Don't use it in a width-constrained cell (a data-grid action column). ButtonGroup flex-wraps and forces --gap-md — two icon buttons overflow a narrow (~120px) column and wrap onto a second line (portal #2782). Keep a non-wrapping <Stack direction="horizontal" gap="xs" justify="end"> in those cells; reach for ButtonGroup only where the row has room (footers, bars).

Accessibility

• Renders a <div role="group"> container. Each child Button keeps its own keyboard semantics.
• Tab order follows DOM order — for vertical groups, primary actions should appear first in source.
• The group has no accessible name by default. If it needs one (e.g. radiogroup-like behavior), pass aria-label / aria-labelledby — the role="group" is already applied.

API

ButtonGroup

Plus all standard <div> HTML attributes.

Related

• Button — the primary child component
• Storybook playground — live variants and patterns