Button Group

Common Button Group Variants

Size Variants

Shape Variants

Use the Border Radius Generator to preview these:

Button Group Properties

Important: When using a button group as a segmented control (selection behavior), it must communicate its role semantically. The group needs role="group" with aria-label, and each button needs aria-pressed="true|false". For exclusive single-selection, consider using role="radiogroup" with role="radio" on each button instead. See the Button component for individual button props.

Design Token Mappings

Border Collapse Logic

The key to button group styling is border management:

/* Connected button group */
.btn-group > button { border-radius: 0; }
.btn-group > button:first-child { border-top-left-radius: var(--radius-md); border-bottom-left-radius: var(--radius-md); }
.btn-group > button:last-child { border-top-right-radius: var(--radius-md); border-bottom-right-radius: var(--radius-md); }
.btn-group > button + button { margin-left: -1px; } /* Collapse borders */

Button Group States

Segmented Control Selection States

Accessibility

Button groups require careful ARIA implementation because they can function as either a group of independent actions or a selection control.

Role Assignment (WCAG 4.1.2 – Name, Role, Value):

• Toolbar pattern: Use role="toolbar" with aria-label on the container. Each button is a standard <button>. Arrow keys navigate between buttons, Tab moves to/from the toolbar.
• Segmented control (single select): Use role="radiogroup" on the container with aria-label. Each button gets role="radio" with aria-checked="true|false". Arrow keys move selection.
• Toggle buttons (multi select): Use role="group" with aria-label. Each button uses aria-pressed="true|false".
• Never mix patterns — pick one and apply consistently.

Keyboard Navigation (WCAG 2.1.1 – Keyboard):

• Toolbar/radiogroup: Arrow Left/Right (or Up/Down for vertical) moves focus between buttons. Home/End jump to first/last. The group is a single Tab stop.
• Toggle group: Each button is individually Tab-focusable (standard button behavior). No arrow key navigation needed.
• Focus must be visible on the active button — ensure the focus ring is not clipped by overflow: hidden on the group container.

Contrast (WCAG 1.4.3 – Contrast Minimum):

• Selected button text must achieve 4.5:1 against the selected background. Use the Contrast Checker.
• Unselected button text must achieve 4.5:1 against the unselected background.
• The visual boundary between selected and unselected buttons must be perceivable — don't rely solely on background color. Consider adding a border or weight change.

Non-Text Contrast (WCAG 1.4.11):

• The group's outer border (if present) must achieve 3:1 against the page background.
• Dividers between buttons must achieve 3:1 if they carry meaning (separating distinct sections).

Grouping (WCAG 1.3.1 – Info and Relationships):

• Always provide aria-label or aria-labelledby on the group container describing the group's purpose: "Text formatting options", "View mode", "Pagination".
• For segmented controls, the label must indicate what's being selected: "Display density" not "Buttons".

Usage Guidelines

Do:

• Limit button groups to 2–5 buttons. More than 5 creates cognitive overload and layout issues on mobile.
• Use consistent button variants within a group — all outlined, or all ghost. Don't mix filled and outlined.
• Provide aria-label describing the group's purpose on the container element.
• For segmented controls, pre-select a default value so the control is never in an ambiguous empty state.
• Use icon-only buttons with aria-label in toolbars. See Icon Button.
• Collapse to a Dropdown Menu on small screens when the group has >3 buttons.

Don't:

• Don't use a button group for primary + secondary action pairs — they should be separate Buttons with hierarchy.
• Don't mix different sizes within a single button group.
• Don't put destructive actions inside a button group without visual distinction — at minimum, color the destructive button differently.
• Don't nest button groups inside other button groups.
• Don't use a segmented control as navigation — use Tabs instead. The distinction: tabs change content panels, segmented controls change how content is displayed (view mode, sort order, density).

Design System Implementations

Material Design (MUI) provides <ButtonGroup> with variant (contained, outlined, text), orientation (horizontal, vertical), size, and color props. For segmented controls, MUI uses <ToggleButtonGroup> with exclusive prop and <ToggleButton> children that support value and selected. MUI handles border collapse internally — middle buttons have border-radius: 0, and overlapping borders are managed via negative margins with z-index on hover/focus. The disableElevation prop removes box-shadow from contained variants.

Ant Design provides <Button.Group> which renders a <div> wrapping standard <Button> components. Ant uses the :not(:first-child):not(:last-child) CSS pattern to zero out internal radii. For segmented controls, Ant Design v5 introduced the <Segmented> component — a standalone component with options, value, onChange, and block (full-width) props. Segmented supports icons, labels, and custom renders per option.

Chakra UI offers <ButtonGroup> with isAttached (connected), spacing (separated), size, and variant props. Chakra passes size and variant to all child <Button> components via context. The isAttached prop triggers the border-radius and margin collapsing logic. Chakra does not include a segmented control — teams build one with useRadioGroup hook and styled radio buttons. Preview your border-radius values with the Border Radius Generator.

Bootstrap implements button groups via the .btn-group class with role="group". Bootstrap handles border-radius collapsing, z-index stacking, and border overlap through detailed CSS selectors. The .btn-group-vertical modifier creates vertical stacks. Bootstrap also provides .btn-toolbar for grouping multiple .btn-group elements with consistent spacing. For toggle behavior, Bootstrap's JavaScript plugin adds .active class and aria-pressed management.

Apple Human Interface Guidelines defines the Segmented Control as the primary multi-button pattern. In UIKit, UISegmentedControl supports text and image segments with a sliding selection indicator. SwiftUI's Picker with .pickerStyle(.segmented) creates the same control declaratively. Apple's segmented controls always enforce single selection and are limited to 5 segments. They should only change content presentation, never navigate. See the Button page for Apple's standard button guidance.

Tailwind CSS button groups are built with flexbox utilities: inline-flex on the container, rounded-none on middle children, rounded-l-md on first, rounded-r-md on last, and -ml-px for border collapse. Tailwind UI and Headless UI provide pre-built <RadioGroup> components for segmented control behavior with full keyboard and ARIA support. The utility-first approach gives maximum flexibility but requires manual implementation of state management and accessibility attributes.