toc

Button Group

A button group arranges related buttons and can manage their selection, density and overflow.

Left

Center

Right

<md-gb-button-group aria-label="Text alignment">
  <md-gb-button color="tonal">Left</md-gb-button>
  <md-gb-button color="tonal">Center</md-gb-button>
  <md-gb-button color="tonal">Right</md-gb-button>
</md-gb-button-group>

Install with shadcn/ui: npx shadcn@latest add https://material-web.dev/3.0/r/md-button-group.json (setup)

Usage guidelines

Link to “Usage guidelines”

Choose standard or connected. In a standard group, buttons respond to the one that is pressed; a connected group joins them into one control.
Keep buttons alike. Use the same size and shape for every button, and mix sizes only for hero moments.
Group related buttons. Mix colors and widths to emphasize what matters and to group related actions.
Let it adapt. On narrow screens, trailing buttons can collapse into an overflow menu.

This component is new in M3 Expressive.

Anatomy

Link to “Anatomy”

A button group holds md-gb-button elements, each with an optional icon.

content_cut Cut

content_copy Copy

content_paste Paste

<md-gb-button-group>
  <md-gb-button color="tonal">
    <md-gb-icon>content_cut</md-gb-icon>
    Cut
  </md-gb-button>
  <md-gb-button color="tonal">
    <md-gb-icon>content_copy</md-gb-icon>
    Copy
  </md-gb-button>
  <md-gb-button color="tonal">
    <md-gb-icon>content_paste</md-gb-icon>
    Paste
  </md-gb-button>
</md-gb-button-group>

Examples

Link to “Examples”

Connected

Link to “Connected”

Set variant="connected" for buttons that sit together as a single control.

Day

Week

Month

<md-gb-button-group variant="connected" aria-label="View">
  <md-gb-button color="outlined">Day</md-gb-button>
  <md-gb-button color="outlined">Week</md-gb-button>
  <md-gb-button color="outlined">Month</md-gb-button>
</md-gb-button-group>

Selection

Link to “Selection”

Set selection to single or multiple and give each button a value. Add required to keep one selected in a single-select group. A group fires input and change when selection changes.

Day

Week

Month

<md-gb-button-group variant="connected" selection="single" required aria-label="View">
  <md-gb-button value="day" color="outlined">Day</md-gb-button>
  <md-gb-button value="week" color="outlined" selected>Week</md-gb-button>
  <md-gb-button value="month" color="outlined">Month</md-gb-button>
</md-gb-button-group>

Icons

Link to “Icons”

Buttons in a group can be icon-only. Give each one an aria-label.

thumb_up

favorite

<md-gb-button-group aria-label="Reactions">
  <md-gb-button color="tonal" aria-label="Like">
    <md-gb-icon>thumb_up</md-gb-icon>
  </md-gb-button>
  <md-gb-button color="tonal" aria-label="Favorite">
    <md-gb-icon>favorite</md-gb-icon>
  </md-gb-button>
  <md-gb-button color="tonal" aria-label="Share">
    <md-gb-icon>share</md-gb-icon>
  </md-gb-button>
</md-gb-button-group>

Density

Link to “Density”

Set density from 0 (default) to -3 to make the buttons shorter. Touch targets stay 48px.

Left

Center

Right

<md-gb-button-group density="-2" aria-label="Text alignment">
  <md-gb-button color="tonal">Left</md-gb-button>
  <md-gb-button color="tonal">Center</md-gb-button>
  <md-gb-button color="tonal">Right</md-gb-button>
</md-gb-button-group>

Link to “Overflow menu”

Add overflow-menu to collapse the buttons that don't fit into a menu at the trailing edge. Choosing a menu entry clicks the original button.

Copy

Paste

Cut

Delete

<md-gb-button-group overflow-menu aria-label="Actions" style="width: 240px">
  <md-gb-button color="tonal">Copy</md-gb-button>
  <md-gb-button color="tonal">Paste</md-gb-button>
  <md-gb-button color="tonal">Cut</md-gb-button>
  <md-gb-button color="tonal">Delete</md-gb-button>
</md-gb-button-group>

Accessibility

Link to “Accessibility”

The group does not need a label of its own, but a name such as aria-label="Text alignment" helps when the buttons form a set.
Label each button as you would a button; icon-only buttons need aria-label.
Tab enters the group, Arrow keys move between buttons, and Enter or Space activates the focused button.

Compatibility

Link to “Compatibility”

Material Design 3Spec checked28% tokens

133 of 210 buildable spec units are tested, 2 are excluded with a written reason and 0 are uncovered (the target is 0). 10 of 36 token declarations match the spec (28%), and 26 have no spec token.

button-groups on m3.material.io (opens in a new tab) How compliance is measured

BaselineWidely availableChrome 124Edge 124Firefox 125Safari 17.4

The component’s own CSS and JavaScript rely only on web platform features that are Baseline widely available: it works in Chrome 124, Edge 124, Firefox 125, Safari 17.4 and later.

Newer features it uses where the browser has them (progressive enhancements):

calc-size() (opens in a new tab) Limited availability used inside an @supports guard
interpolate-size (opens in a new tab) Limited availability degrades safely where it is missing

Browser support Learn more about Baseline (opens in a new tab)

WAI-ARIAaxe and ARIA 1.3 passToolbar

Roles the component renders: toolbar (opens in a new tab).

Follows the WAI-ARIA Authoring Practices: Toolbar (opens in a new tab).

1 rendered state run through axe-core and the WAI-ARIA 1.3 role and attribute rules in a real browser, with no known gaps.

WAI-ARIA 1.3 (opens in a new tab) ARIA Authoring Practices (opens in a new tab) Accessibility

Lighthouse90 · 100 · 100 · 100

Performance
Accessibility
Best practices
SEO

Audits under 90:

First Contentful Paint
Largest Contentful Paint
Largest Contentful Paint element
Eliminate render-blocking resources
Minify JavaScript
Reduce unused CSS
Reduce unused JavaScript
Enable text compression
Network dependency tree
Render blocking requests

Lighthouse 12.8.2 (desktop, 2026-11-08) on the component alone: its first example on a page of its own, without this site's shell. The modules are the development build (not bundled or minified), so the performance score is indicative.

Open the test page About Lighthouse (opens in a new tab)

API reference

Link to “API reference”

<md-gb-button-group>

Link to “<md-gb-button-group>”

A Material Design button group.

Properties

Link to “Properties”

Property	Attribute	Type	Default
`density` The density of the buttons inside, from 0 (default) to -3. Each step down removes 4px from the buttons' height (button-groups.md: "Button groups adapt to the height of the buttons inside, including when density is applied"); touch targets stay 48px. A button's own non-zero `density` wins. Values are clamped to that range.	`density`	`Density`
`disabled` Whether the button group is disabled.	`disabled`	`boolean`	`false`
`overflowMenu` Whether the buttons at the trailing edge that do not fit collapse into a trailing overflow menu, and come back when the group has room again (button-groups.md, Adaptive design: "Buttons at the trailing edge of the button group can be customized to collapse into an overflow menu at smaller breakpoints, and become visible again at larger sizes."). The group is as wide as its container allows: give it a width, or put it in a narrower container, to make buttons overflow. Choosing a menu entry clicks the original button.	`overflow-menu`	`boolean`	`false`
`required` Whether selection is required in single-select mode.	`required`	`boolean`	`false`
`resizing` How the group and its buttons resize (button-groups.md, Resizing). `fixed`: every button keeps the width its own size and width give it. `flexible`: the group fills the width of its container and its buttons grow with it; an icon button does not stretch past its set width, and a button with `resizing="fixed"` keeps its width. A button with `resizing="flexible"` in a fixed group grows when the group is given more width. Unset: a connected group is flexible (it spans its surface), a standard group is fixed.	`resizing`	`ButtonGroupResizing`	`""`
`selection` The selection mode.	`selection`	`ButtonGroupSelection`	`"none"`
`variant` The visual variant of the button group.	`variant`	`ButtonGroupVariant`	`"standard"`

Slots

Link to “Slots”

Slot	Description
default	Used to display buttons.
`overflow`	Replaces the default overflow button (see `overflowMenu`).

Events

Link to “Events”

Event	Description
`change` Event	Fired when selection changes.
`input` InputEvent	Fired when selection changes.

CSS custom properties

Link to “CSS custom properties”

Property	Description
`--between-space`
`--density-step`	Button height removed per density step.
`--inner-corner-size`
`--motion-spring-fast-spatial`
`--motion-spring-fast-spatial-duration`
`--outer-corner-size`
`--outer-corner-square-size`
`--pressed-inner-corner-size`
`--pressed-item-width-multiplier`