toc

Segmented button

A segmented button set lets people pick one or several options from two to five segments, such as a time range or a view.

View as Markdown

Day

Week

Month

<md-gb-segmented-button-set aria-label="Time range">
  <md-gb-segmented-button value="day" selected>Day</md-gb-segmented-button>
  <md-gb-segmented-button value="week">Week</md-gb-segmented-button>
  <md-gb-segmented-button value="month">Month</md-gb-segmented-button>
</md-gb-segmented-button-set>

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

Usage guidelines

Link to “Usage guidelines”

Prefer a connected button group. Material 3 Expressive no longer recommends segmented buttons; the connected button group has mostly the same function with an updated look.
Keep it to two to five segments. For more options or more complex choices, use chips.
Pick the selection mode. A set is single-select by default; add multiselect when people can choose several.
Use icons, labels or both. Make sure each icon-only segment has an accessible name.

Anatomy

Link to “Anatomy”

A segmented button set holds segments. Each segment has a label and an optional icon.

view_list List

grid_view Grid

<md-gb-segmented-button-set aria-label="View">
  <md-gb-segmented-button selected>
    <md-gb-icon slot="icon">view_list</md-gb-icon>
    List
  </md-gb-segmented-button>
  <md-gb-segmented-button>
    <md-gb-icon slot="icon">grid_view</md-gb-icon>
    Grid
  </md-gb-segmented-button>
</md-gb-segmented-button-set>

Examples

Link to “Examples”

Multi-select

Link to “Multi-select”

Add multiselect to the set so people can select more than one segment. A selected segment shows a checkmark; add no-checkmark to a segment to hide it.

Vegan

Gluten free

Nut free

<md-gb-segmented-button-set aria-label="Filters" multiselect>
  <md-gb-segmented-button value="vegan" selected>Vegan</md-gb-segmented-button>
  <md-gb-segmented-button value="gluten-free">Gluten free</md-gb-segmented-button>
  <md-gb-segmented-button value="nut-free">Nut free</md-gb-segmented-button>
</md-gb-segmented-button-set>

Icons

Link to “Icons”

Put an md-gb-icon in the icon slot, with or without a label. An icon-only segment needs an aria-label.

view_list List

grid_view Grid

format_align_left

format_align_center

format_align_right

<md-gb-segmented-button-set aria-label="Layout">
  <md-gb-segmented-button value="list" selected>
    <md-gb-icon slot="icon">view_list</md-gb-icon>
    List
  </md-gb-segmented-button>
  <md-gb-segmented-button value="grid">
    <md-gb-icon slot="icon">grid_view</md-gb-icon>
    Grid
  </md-gb-segmented-button>
</md-gb-segmented-button-set>
<md-gb-segmented-button-set aria-label="Text alignment">
  <md-gb-segmented-button value="left" selected aria-label="Left">
    <md-gb-icon slot="icon">format_align_left</md-gb-icon>
  </md-gb-segmented-button>
  <md-gb-segmented-button value="center" aria-label="Center">
    <md-gb-icon slot="icon">format_align_center</md-gb-icon>
  </md-gb-segmented-button>
  <md-gb-segmented-button value="right" aria-label="Right">
    <md-gb-icon slot="icon">format_align_right</md-gb-icon>
  </md-gb-segmented-button>
</md-gb-segmented-button-set>

Required

Link to “Required”

In a single-select set, add required so a segment always stays selected and the selected one can't be unselected.

Small

Medium

Large

<md-gb-segmented-button-set aria-label="Cup size" required>
  <md-gb-segmented-button value="small">Small</md-gb-segmented-button>
  <md-gb-segmented-button value="medium" selected>Medium</md-gb-segmented-button>
  <md-gb-segmented-button value="large">Large</md-gb-segmented-button>
</md-gb-segmented-button-set>

Disabled

Link to “Disabled”

Add disabled to a segment, or to the set to disable every segment.

Name

Date

Size

<md-gb-segmented-button-set aria-label="Sort by">
  <md-gb-segmented-button value="name" selected>Name</md-gb-segmented-button>
  <md-gb-segmented-button value="date">Date</md-gb-segmented-button>
  <md-gb-segmented-button value="size" disabled>Size</md-gb-segmented-button>
</md-gb-segmented-button-set>

Density

Link to “Density”

Set density on the set from 0 (default, 40px tall) down to -3 to remove 4px of height per step. Keep it off by default and let people opt in.

Day

Week

<md-gb-segmented-button-set aria-label="Range" density="-2">
  <md-gb-segmented-button value="day" selected>Day</md-gb-segmented-button>
  <md-gb-segmented-button value="week">Week</md-gb-segmented-button>
</md-gb-segmented-button-set>

In a form

Link to “In a form”

The set is form-associated. Give it a name and it submits the selected segment's value, one entry for each selected segment in a multi-select set. It fires input and change when people change the selection.

HTML

<form>
  <md-gb-segmented-button-set name="range" aria-label="Time range">
    <md-gb-segmented-button value="day" selected>Day</md-gb-segmented-button>
    <md-gb-segmented-button value="week">Week</md-gb-segmented-button>
  </md-gb-segmented-button-set>
  <output></output>
</form>

const form = document.querySelector('form');
const output = document.querySelector('output');
const show = () => {
  output.textContent = `range=${new FormData(form).get('range')}`;
};
form.addEventListener('change', show);
show();

Accessibility

Link to “Accessibility”

Give the set an aria-label that says what the choice is about.
In a single-select set the segments are radios, and in a multi-select set they are checkboxes. Tab enters the set, the arrow keys move between segments, and Space or Enter selects the focused one.
Icon-only segments need an aria-label.
A disabled segment is skipped by the keyboard.

Compatibility

Link to “Compatibility”

Material Design 3Spec checked70% tokens

56 of 149 buildable spec units are tested, 0 are excluded with a written reason and 0 are uncovered (the target is 0). 16 of 23 token declarations match the spec (70%), and 7 have no spec token.

segmented-buttons 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):

Cursor styles (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 passButtonCheckbox

Roles the component renders: button (opens in a new tab), checkbox (opens in a new tab), group (opens in a new tab), radiogroup (opens in a new tab).

Follows the WAI-ARIA Authoring Practices: Button (opens in a new tab), Checkbox (opens in a new tab), Radio Group (opens in a new tab).

3 rendered states 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

Lighthouse99 · 100 · 100 · 100

Performance
Accessibility
Best practices
SEO

Audits under 90:

Eliminate render-blocking resources
Minify 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-segmented-button>

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

One segment of a Material Design segmented button set.

Properties

Link to “Properties”

Property	Attribute	Type	Default
`disabled` Whether the segment is disabled.	`disabled`	`boolean`	`false`
`focusable` Whether the segment is the set's tab stop (roving `tabindex`). Set by `md-gb-segmented-button-set`.		`boolean`	`true`
`groupDisabled` Whether the parent set is disabled. Set by `md-gb-segmented-button-set`.		`boolean`	`false`
`label` Label text, rendered before the default slot's content.	`label`	`string`	`''`
`mode` The selection mode of the parent set: `radio` semantics for `single`, `checkbox` for `multiple`. Set by `md-gb-segmented-button-set`.		`SegmentedButtonMode`	`'single'`
`noCheckmark` Whether to hide the checkmark that shows when selected.	`no-checkmark`	`boolean`	`false`
`selected` Whether the segment is selected.	`selected`	`boolean`	`false`
`value` The value submitted with the set's form when selected.	`value`	`string`	`''`

Slots

Link to “Slots”

Slot	Description
default	The label text.
`icon`	An optional leading icon, such as `<md-gb-icon>`.

CSS parts

Link to “CSS parts”

Part	Description
`::part(button)`	The segment's `<button>`.

CSS custom properties

Link to “CSS custom properties”

Property	Description
`--container-height`	Segment height at density 0.
`--container-shape`	Outer corner radius of the first and last segments.
`--density-step`	Height removed per density step.
`--icon-label-space`	Space between the icon and the label.
`--icon-size`	Icon and checkmark size.
`--label-text`	Label typography.
`--label-text-axes`	Label font variation settings.
`--label-text-tracking`	Label letter spacing.
`--leading-space`	Padding before the content.
`--min-width`	Minimum segment width.
`--outline-color`	Outline color.
`--outline-width`	Outline width.
`--target-size`	Minimum touch target height.
`--trailing-space`	Padding after the content.

<md-gb-segmented-button-set>

Link to “<md-gb-segmented-button-set>”

A Material Design segmented button set.

Properties

Link to “Properties”

Property	Attribute	Type	Default
`density` The density, from 0 (default, 40px) to -3. Each step down removes 4px from the height. Values are clamped to that range.	`density`	`SegmentedButtonDensity`
`multiselect` Whether more than one segment can be selected.	`multiselect`	`boolean`	`false`
`required` In single-select mode, whether a segment must stay selected: the selected segment can't be unselected.	`required`	`boolean`	`false`

Slots

Link to “Slots”

Slot	Description
default	The `md-gb-segmented-button` segments.

Events

Link to “Events”

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

CSS custom properties

Link to “CSS custom properties”

Property	Description
`--container-height`	Segment height at density 0.
`--container-shape`	Outer corner radius of the first and last segments.
`--density-step`	Height removed per density step.
`--icon-label-space`	Space between the icon and the label.
`--icon-size`	Icon and checkmark size.
`--label-text`	Label typography.
`--label-text-axes`	Label font variation settings.
`--label-text-tracking`	Label letter spacing.
`--leading-space`	Padding before each segment's content.
`--min-width`	Minimum segment width.
`--outline-color`	Outline color.
`--outline-width`	Outline width.
`--target-size`	Minimum touch target height.
`--trailing-space`	Padding after each segment's content.

Segmented button

Usage guidelines

Anatomy

Examples

Multi-select

Icons

Required

Disabled

Density

In a form

Accessibility

Compatibility

API reference

<md-gb-segmented-button>

Properties

Slots

CSS parts

CSS custom properties

<md-gb-segmented-button-set>

Properties

Slots

Events

CSS custom properties

Download & copy

Download

Copy

Customize theme