@material/segmented-button
Advanced tools
Changelog
14.0.0 (2022-04-27)
unset is unsupported in IE. (f460e23)validateTooltipWithCaretDistances method. (3e30054)theme-styles mixin... the value being retreived from the $theme map and css property name was swapped. The mixin would request font-size/font-weight/letter-spacing from the $theme map (which expects size/weight/tracking)... so these values would always be null. (32b3913)attachTo. (05db65e)showTimeout is not set (indicating that this tooltip is about to be re-shown). (6ca8b8f)minRange param to range sliders to request a minimum gap between the two thumbs. (8fffcb5)valueToAriaValueTextFn and valueToValueIndicatorTextFn functions are called for. (b6510c8)PiperOrigin-RevId: 444830518
PiperOrigin-RevId: 419837612
Readme
Segmented buttons allow users to toggle the selected states of grouped buttons.
npm install @material/segmented-button
<div class="mdc-segmented-button" role="group">
<button class="mdc-segmented-button__segment" aria-pressed="false">
<i class="material-icons mdc-segmented-button__icon">favorite</i>
</button>
<button class="mdc-segmented-button__segment" aria-pressed="false">
<div class="mdc-segmented-button__label">Sample Text</div>
</button>
<button class="mdc-segmented-button__segment" aria-pressed="false">
<i class="material-icons mdc-segmented-button__icon">favorite</i>
<div class="mdc-segmented-button__label">Sample Text</div>
</button>
</div>
@use '@material/ripple/common';
@use '@material/segmented-button/styles';
import {MDCSegmentedButton} from '@material/segmented-button';
const segmentedButtonEl = document.querySelector('.mdc-segmented-button');
const segmentedButton = new MDCSegmentedButton(segmentedButtonEl);
See Importing the JS component for more information on how to import JavaScript.
The MDC Segmented Button component automatically instantiates the child MDC Segmented Button Segment components.
We recommend using Material Icons from Google Fonts:
<head>
<link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
</head>
However, you can also use SVG, FontAwesome, or any other icon library you wish.
By default, the segmented button allows any number of segments to be selected at a time so that each segment is independent from the rest.
For accessibility, the segments are treated as toggle buttons. The segmented button is assigned role="group" and each segment has the attribute aria-pressed with a boolean value corresponding to its selected state.
<div class="mdc-segmented-button" role="group">
<button class="mdc-segmented-button__segment" aria-pressed="false">
<i class="material-icons mdc-segmented-button__icon">favorite</i>
</button>
<button class="mdc-segmented-button__segment" aria-pressed="false">
<div class="mdc-segmented-button__label">Sample Text</div>
</button>
<button class="mdc-segmented-button__segment" aria-pressed="false">
<i class="material-icons mdc-segmented-button__icon">favorite</i>
<div class="mdc-segmented-button__label">Sample Text</div>
</button>
</div>
The segmented button can be limited to select only one segment at a time. In this case, the selected segment cannot be unselected with a click. Selecting a different segment will unselect the previously selected segment. To make the segmented button single select, add the class mdc-segmented-button--single-select.
For accessibility, the segments are treated as radio buttons. The segmented button is assigned role="radiogroup" and each segment is assigned role="radio" and has the attribute aria-checked with a boolean value corresponding to its selected state.
<div class="mdc-segmented-button mdc-segmented-button--single-select" role="radiogroup">
<button class="mdc-segmented-button__segment" role="radio" aria-checked="false">
<i class="material-icons mdc-segmented-button__icon">favorite</i>
</button>
<button class="mdc-segmented-button__segment" role="radio" aria-checked="false">
<div class="mdc-segmented-button__label">Sample Text</div>
</button>
<button class="mdc-segmented-button__segment" role="radio" aria-checked="false">
<i class="material-icons mdc-segmented-button__icon">favorite</i>
<div class="mdc-segmented-button__label">Sample Text</div>
</button>
</div>
The segment is assumed to be a child of a segmented button. The segment can be in a selected or unselected state and changes state if the button is clicked or if the segmented button tells it to change its state. If the parent segmented button is single select and the segment is selected, the segment will not become unselected if it is clicked.
The segment can contain an icon, text, or both. If both an icon and text are used, the icon is assumed to come first (unless the page is loaded as rtl). Ripple effects and touch support can also be added.
To insert text inside of a segment, add the class mdc-segmented-button__label.
<button class="mdc-segmented-button__segment">
<div class="mdc-segmented-button__label">Sample Text</div>
</button>
To insert an icon inside of a segment, add the class mdc-segmented-button__icon.
<button class="mdc-segmented-button__segment">
<i class="material-icons mdc-segmented-button__icon">favorite</i>
</button>
The segment will remain in a visually toggled state while selected. To select the segment by default, add the class mdc-segmented-button__segment--selected and set the attribute aria-pressed or aria-checked (if the segmented button is multi or single select, respectively) to true.
<button class="mdc-segmented-button__segment mdc-segmented-button__segment--selected" aria-pressed="true">
<div class="mdc-segmented-button__label">Sample Text</div>
</button>
Material Design spec advises that touch targets should be at least 48 x 48 px. To meet this requirement, add the following to your segments:
<div class="mdc-touch-target-wrapper">
<button class="mdc-segmented-button__segment mdc-segmented-button--touch">
<div class="mdc-segmented-button__touch"></div>
<div class="mdc-segmented-button__label">Sample Text</div>
</button>
</div>
To include ripple effects when a segment is clicked add the following classes to the segment:
<button class="mdc-segmented-button__segment">
<div class="mdc-segmented-button__ripple"></div>
<div class="mdc-segmented-button__label">Sample Text</div>
</button>
Each segment within the segmented button is a tabbable element. Arrow key navigation between segments is not supported at this time.
| CSS Class | Description |
|---|---|
mdc-segmented-button | Mandatory. Indicates the wrapper for child segments. |
mdc-segmented-button__single-select | Optional. Indicates the segmented button only allows one segment to be selected at a time. |
mdc-segmented-button__segment | Mandatory. Indicates a button element that can be selected. |
mdc-segmented-button__icon | Optional. Indicates an icon in the segment. We recommend using Material Icons from Google Fonts. |
mdc-segmented-button__label | Optional. Indicates text in the segment. |
mdc-segmented-button__segment--selected | Optional. Indicates that the segment is selected. |
mdc-touch-target-wrapper | Optional. Indicates contained segment has touch target support. |
mdc-segmented-button--touch | Optional. Indicates the segment has touch target support. |
mdc-segmented-button__touch | Optional. Indicates the segment has touch target support. |
mdc-segmented-button__ripple | Optional. Indicates the segment has a ripple effect when clicked. |
NOTE: Every segment element must contain an icon with class
mdc-segmented-button__icon, text with classmdc-segmented-button__label, or both.
NOTE: While
mdc-touch-target-wrapper,mdc-segmented-button--touch, andmdc-segmented-button__touchare optional, if one is used then all three must be used.
| Mixin | Description |
|---|---|
outline-color | Customizes the border color around each segment. |
unselected-ink-color | Customizes the text and icon ink color for an unselected segment. |
unselected-container-fill-color | Customizes the background color for an unselected segment. |
selected-ink-color | Customizes the text and icon ink color for a selected segment. |
selected-container-fill-color | Customizes the background color for an selected segment. |
MDCSegmentedButton, MDCSegmentedButtonSegment, and SegmentDetail Properties and MethodsThe MDC Segmented Button package is composed of two JavaScript classes:
MDCSegmentedButton defines the behavior of a set of segments.MDCSegmentedButtonSegment defines the behavior of a single segment.To use the MDCSegmentedButton and MDCSegmentedButtonSegment classes, import both from @material/segmented-button.
SegmentDetailThe SegmentDetail type contains only the actionable information about a specific MDCSegmentedButtonSegment.
| Property | Value Type | Description |
|---|---|---|
index | number | The index of the segment. |
selected | boolean | The segment's selected state. |
segmentId? | string | undefined | The segment's segmentId, if provided. |
MDCSegmentedButton| Method Signature | Description |
|---|---|
getSelectedSegments() => readonly SegmentDetail[] | Proxies to foundation's getSelectedSegments method. |
selectSegment(indexOrSegmentId: number | string) => void | Proxies to foundation's selectSegment method. |
unselectSegment(indexOrSegmentId: number | string) => void | Proxies to foundation's unselectSegment method. |
isSegmentSelected(indexOrSegmentId: number | string) => boolean | Proxies to foundation's isSegmentSelected method. |
| Property | Value Type | Description |
|---|---|---|
segments | ReadOnlyArray<MDCSegmentedButtonSegment> | Array of child MDCSegmentedButtonSegments. |
ripple | MDCRipple (read-only) | The MDCRipple instance for the root element that MDCSegmentedButton initializes. |
| Event Name | event.detail | Description |
|---|---|---|
| MDCSegmentedButton:change | SegmentDetail | Indicates that a segment's selected value may have changed due to a click. |
MDCSegmentedButtonSegment| Method Signature | Description |
|---|---|
setIndex(index: number) => void | Sets segment's index. |
setIsSingleSelect(isSingleSelect: boolean) => void | Sets segment's isSingleSelect. |
isSelected() => boolean | Proxies to foundation's isSelected method. |
setSelected() => void | Proxies to foundation's setSelected method. |
setUnselected() => void | Proxies to foundation's setUnselected method. |
getSegmentId() => string | undefined | Proxies to foundation's getSegmentId method. |
| Event Name | event.detail | Description |
|---|---|---|
MDCSegmentedButtonSegment:selected | SegmentDetail | Indicates the segment's selected status just changed due to a click. |
If you are using a JavaScript framework, such as React or Angular, you can create Segmented Buttons for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.
MDCSegmentedButtonAdapter and MDCSegmentedButtonSegmentAdapterSee segmented-button/component.ts and segment/component.ts for vanilla DOM implementations of these adapter APIs for reference.
MDCSegmentedButtonAdapter| Method Signature | Description |
|---|---|
hasClass(className: string) => boolean | Returns true if segmented button has className, otherwise returns false. |
getSegments() => readonly SegmentDetail[] | Returns child segments represented as a readonly list of SegmentDetails. |
selectSegment(indexOrSegmentId: number | string) => void | Sets identified segment to be selected. |
unselectSegment(indexOrSegmentId: number | string) => void | Set identified segment to be not selected. |
notifySelectedChange(detail: SegmentDetail) => void | Notifies the client about the changed segment with a change event. |
NOTE:
notifySelectedChangemust pass along aSegmentDetailrepresenting the potentially changed Segment, and must be observable by the client (e.g. via DOM event bubbling).
MDCSegmentedButtonSegmentAdapter| Method Signature | Description |
|---|---|
isSingleSelect() => boolean | Returns true if wrapping segmented button is single select, otherwise returns false. |
getAttr(attrName: string) => string | null | Returns root element's attribute if it is set, otherwise returns null. |
setAttr(attrName: string, value: string) => void | Sets root element's attribute value to value. |
addClass(className: string) => void | Adds class to the root element. |
removeClass(className: string) => void | Removes class from the root element. |
hasClass(className: string) => boolean | Returns true if root element has class, otherwise returns false. |
notifySelectedChange(selected: boolean) => void | Notifies the Segmented Button that the segment's selected state has changed. |
NOTE:
notifySelectedChangemust pass along aSegmentDetailrepresenting the Segment, and must be observable by themdc-segmented-buttonelement (e.g. via DOM event bubbling).
MDCSegmentedButtonFoundation and MDCSegmentedButtonSegmentFoundationMDCSegmentedButtonFoundation| Method Signature | Description |
|---|---|
selectSegment(indexOrSegmentId: number | string) => void | Sets identified segment to be selected. |
unselectSegment(indexOrSegmentId: number | string) => void | Set identified segment to be not selected. |
getSelectedSegments() => readonly SegmentDetail[] | Returns selected segments as readonly list of SegmentDetails. |
isSegmentSelected(indexOrSegmentId: number | string) => boolean | Returns true if identified segment is selected, otherwise returns false. |
isSingleSelect() => boolean | Returns true if segmented button is single select, otherwise returns false. |
handleSelected(detail: SegmentDetail) => void | Handles a selected event. Maintains single select restrictions, if applicable, and notifies client. |
MDCSegmentedButtonFoundation Event HandlersWhen wrapping the Segmented Button foundation, the following events must be bound to the indicated foundation methods:
| Events | Element Selector | Foundation Handler |
|---|---|---|
MDCSegmentedButtonSegment:selected | .mdc-segmented-button (root) | handleSelected |
MDCSegmentedButtonSegmentFoundation| Method Signature | Description |
|---|---|
isSelected() => void | Returns true if segment is currently selected. |
setSelected() => void | Sets segment to be selected. |
setUnselected() => void | Sets segment to be not selected. |
getSegmentId() => string | undefined | Returns segment's segmentId if it was provided, otherwise return undefined. |
handleClick() => void | Handles a click event. Changes selected state if able (due to single select) and notifies Segmented Button. |
MDCSegmentedButtonSegmentFoundation Event HandlersWhen wrapping the Segment foundation, the following events must be bound to the indicated foundation methods:
| Events | Element Selector | Foundation Handler |
|---|---|---|
click | .mdc-segmented-button__segment (root) | handleClick |
FAQs
The Material Components for the web segmented button component
The npm package @material/segmented-button receives a total of 724,449 weekly downloads. As such, @material/segmented-button popularity was classified as popular.
We found that @material/segmented-button demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 15 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.
Security News
UnitedHealth Group disclosed that the ransomware attack on Change Healthcare compromised protected health information for millions in the U.S., with estimated costs to the company expected to reach $1 billion.