# 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. **Example: A single-select set of three segments with Day selected** ```html Day Week Month ``` ## Usage guidelines * **Prefer a connected button group.** Material 3 Expressive no longer recommends segmented buttons; the connected [button group](/material-web/3.0/components/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](/material-web/3.0/components/chip/). * **Pick the selection mode.** A set is [single-select](#examples) by default; add [multiselect](#multi-select) when people can choose several. * **Use icons, labels or both.** Make sure each [icon-only](#icons) segment has an accessible name. ## Anatomy A segmented button set holds segments. Each segment has a label and an optional icon. **Example: A segmented button set whose segments have an icon and a label** ```html view_list List grid_view Grid ``` ## Examples ### 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. **Example: A multi-select set of filters** ```html Vegan Gluten free Nut free ``` ### Icons Put an `md-gb-icon` in the `icon` slot, with or without a label. An icon-only segment needs an `aria-label`. **Example: A set of segments with icons and labels, and a set with icons only** ```html view_list List grid_view Grid format_align_left format_align_center format_align_right ``` ### Required In a single-select set, add `required` so a segment always stays selected and the selected one can't be unselected. **Example: A required single-select set** ```html Small Medium Large ``` ### Disabled Add `disabled` to a segment, or to the set to disable every segment. **Example: A set with a disabled segment** ```html Name Date Size ``` ### 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. **Example: A set at density -2** ```html Day Week ``` ### 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. **Example: A form whose segmented button set submits the chosen range** *HTML* ```html
Day Week
``` *JavaScript* ```js 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 * 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. ## API reference ### <md-gb-segmented-button> One segment of a Material Design segmented button set. #### 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 | Slot | Description | | --- | --- | | default | The label text. | | icon | An optional leading icon, such as <md-gb-icon>. | #### CSS parts | Part | Description | | --- | --- | | ::part(button) | The segment's <button>. | #### 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> A Material Design segmented button set. #### 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 | Slot | Description | | --- | --- | | default | The md-gb-segmented-button segments. | #### Events | Event | Description | | --- | --- | | change
Event | Fired when the user changes the selection. | | input
InputEvent | Fired when the user changes the selection. | #### 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. |