Button Group

Material Design 3 button group component for organizing related actions with flexible layout options. Not intended as a replacement for navigation tabs or segmented controls with persistent state.

Basic Usage

Group multiple buttons together with consistent spacing and styling. This keeps related actions visually connected and easier to scan.

One Two Three 
<ds-button-group>
  <ds-button>One</ds-button>
  <ds-button>Two</ds-button>
  <ds-button>Three</ds-button>
</ds-button-group>

Variants

Button groups come in variants to support different spacing and visual styles.

Connected (Default)

Buttons are connected with 2dp spacing and modified border radius on end buttons

One Two Three 
<ds-button-group>
  <ds-button>One</ds-button>
  <ds-button>Two</ds-button>
  <ds-button>Three</ds-button>
</ds-button-group>

Standard

Buttons have 8dp spacing between them

One Two Three 
<ds-button-group variant="standard">
  <ds-button>One</ds-button>
  <ds-button>Two</ds-button>
  <ds-button>Three</ds-button>
</ds-button-group>

Segmented

Segmented styling with shared outline and dividers

One Two Three 
<ds-button-group variant="segmented">
  <ds-button>One</ds-button>
  <ds-button>Two</ds-button>
  <ds-button>Three</ds-button>
</ds-button-group>

Selection

Button groups can manage single or multi-select state

Single Select

Day Week Month 
<ds-button-group selection="single">
  <ds-button value="day">Day</ds-button>
  <ds-button value="week">Week</ds-button>
  <ds-button value="month">Month</ds-button>
</ds-button-group>

Multi-Select

Bold Italic Underline 
<ds-button-group selection="multi">
  <ds-button value="bold">Bold</ds-button>
  <ds-button value="italic">Italic</ds-button>
  <ds-button value="underline">Underline</ds-button>
</ds-button-group>

Orientation

Button groups can be arranged horizontally or vertically

Horizontal (Default)

Left Middle Right 
<ds-button-group>...</ds-button-group>

Vertical

Top Middle Bottom

All buttons match the width of the longest label in vertical groups. 

<ds-button-group orientation="vertical">
  <ds-button>Top</ds-button>
  <ds-button>Middle</ds-button>
  <ds-button>Bottom</ds-button>
</ds-button-group>

With Different Button Variants

Mix different button variants within a group

Filled Outlined Text 
<ds-button-group>
  <ds-button variant="filled">Filled</ds-button>
  <ds-button variant="outlined">Outlined</ds-button>
  <ds-button variant="text">Text</ds-button>
</ds-button-group>

States

Disabled

Disable all buttons in the group at once

One Two Three

Setting disabled on the group propagates to all buttons. 

<ds-button-group disabled>
  <ds-button>One</ds-button>
  <ds-button>Two</ds-button>
  <ds-button>Three</ds-button>
</ds-button-group>

API

Attributes

Attribute Type Default Description
variant string 'connected' Button group variant: 'connected' (2dp gap, modified border radius), 'standard' (8dp gap), or 'segmented' (outlined)
orientation string 'horizontal' Layout direction: 'horizontal' or 'vertical'
disabled boolean false Disables all buttons in the group
selection string 'none' Selection mode: 'none', 'single', 'multi', 'required'

Slots

Slot Description
(default) Button elements to group

CSS Parts

Part Description
container The main container element

Events

Event Detail Description
change { value } Fired when selection changes

CSS Custom Properties

Property Description
--ds-button-group-gap Custom gap between buttons (overrides variant default)

Accessibility

Keyboard Interaction

Key Context Expected Result
Tab / Shift+Tab Button group focused Moves focus between buttons in document order
Enter / Space Focus on button Activates focused button
Arrow Keys Connected variant Navigates between sibling buttons

Semantics

  • role="group" - Identifies button group container
  • aria-label - Provides accessible name for the group
  • Child buttons maintain individual ARIA attributes

Screen Reader Support

  • ✅ Announces button group as a grouped collection
  • ✅ Announces each button individually with its label
  • ✅ Announces disabled state when applied to group
  • ✅ Each button's state changes are announced

Visual Indicators

  • ✅ Individual button focus rings remain visible
  • ✅ Connected variant shows visual relationship between buttons
  • ✅ Disabled state is visually distinct
  • ✅ Sufficient color contrast for all text

Usage Guidelines

  • When to use: Use button groups for small sets of closely related actions that users compare or toggle quickly.
  • When not to use: Avoid button groups for primary app navigation or when actions are unrelated and should be spaced apart.
  • Composition: Choose connected for tight relationship, standard for looser spacing, and segmented for shared-outline style.
  • Common mistakes: Mixing too many variants in one group reduces clarity. Keep labels concise and action count modest.