SegmentedButton

The segmented button group is a component that encapsulates a set of buttons. It is used to provide options, switch views, or sort elements.

Usage

Import the component:

import 'mdui/components/segmented-button-group.js';
import 'mdui/components/segmented-button.js';

Import the TypeScript type:

import type { SegmentedButtonGroup } from 'mdui/components/segmented-button-group.js';
import type { SegmentedButton } from 'mdui/components/segmented-button.js';

Example:

Day Week Month
<mdui-segmented-button-group>
  <mdui-segmented-button>Day</mdui-segmented-button>
  <mdui-segmented-button>Week</mdui-segmented-button>
  <mdui-segmented-button>Month</mdui-segmented-button>
</mdui-segmented-button-group>

Examples

Full Width

To make the component take up the full width of its container, add the full-width attribute to the <mdui-segmented-button-group> component.

Single Selection

To enable single selection mode, set the selects attribute of the <mdui-segmented-button-group> component to single. In this mode, the value property of <mdui-segmented-button-group> reflects the value property of the currently selected <mdui-segmented-button>.

Multiple Selection

To enable multiple selection mode, set the selects attribute of the <mdui-segmented-button-group> component to multiple. In this mode, the value property of <mdui-segmented-button-group> is an array consisting of the value properties of the currently selected <mdui-segmented-button> components.

Note that when supporting multiple selection, the value property of <mdui-segmented-button-group> is an array, and it can only be read and set through JavaScript property.

Icons

To add Material Icons on the left and right sides of the button, use the icon and end-icon attributes on the <mdui-segmented-button> element. Alternatively, use the icon and end-icon slots to add elements on the left and right sides of the button.

To set the Material Icon for the selected state, use the selected-icon attribute on the <mdui-segmented-button> element. Alternatively, use the selected-icon slot.

To turn the button into a link, use the href attribute on the <mdui-segmented-button> component. The download, target, and rel attributes are available for link-related functionality.

Disabled and Loading States

To disable the entire segmented button group, add the disabled attribute to the <mdui-segmented-button-group> element.

To disable specific buttons, add the disabled attribute to the <mdui-segmented-button> element. To make a button enter the loading state, add the loading attribute.

mdui-segmented-button-group API

Properties

AttributePropertyReflectTypeDefault
full-widthfullWidthbooleanfalse

If set, the segmented button group will fill the width of its parent element.

selectsselects'single' | 'multiple'-

Defines selectable states. Default is non-selectable. Possible values:

  • single: Only one can be selected.
  • multiple: Multiple selections are allowed.
disableddisabledbooleanfalse

Disables the segmented button group when set.

requiredrequiredbooleanfalse

Requires a selection when the form is submitted.

formformstring-

Associates the segmented button group with a <form> element. The value should be the id of a <form> in the same document. If not set, the segmented button group is associated with its parent <form>, if any.

This attribute allows segmented button group elements to be associated with <form>s anywhere in the document, not just inside a <form>.

namenamestring''

The name of the segmented button group, which is submitted with form data.

valuevaluestring | string[]''

The value of the selected <mdui-segmented-button>. This value is submitted with form data.

Note: The HTML attribute is always a string and can only be set as an initial value when selects="single". The JavaScript property is a string when selects="single" and an array of strings when selects="multiple". In selects="multiple", this value can only be modified by changing the JavaScript property.

defaultValuestring | string[]''

The default selected value. Resets to this state when the form is reset. This value can only be set via JavaScript property.

validityValidityState-

A ValidityState object that represents the element's validity states.

validationMessagestring-

The element's validation message. This is empty if the element meets its constraints.

Methods

NameParametersReturns
checkValidity
boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event and returns false. If it's valid, it returns true.

reportValidity
boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event, returns false, and displays a validation message. If it's valid, it returns true.

setCustomValidity
  • message: string
void

Sets a custom error message. If the text is non-empty, it indicates that the field is invalid.

Events

Name
change

Emitted when the selected value changes.

invalid

Emitted when the form control's validity is checked and it doesn't meet the constraints.

Slots

Name
(default)

<mdui-segmented-button> elements.

CSS Custom Properties

Name
--shape-corner

The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.

mdui-segmented-button API

Properties

AttributePropertyReflectTypeDefault
iconiconstring-

Specifies the Material Icons name for the left icon. Alternatively, use slot="icon".

end-iconendIconstring-

Specifies the Material Icons name for the right icon. Alternatively, use slot="end-icon".

selected-iconselectedIconstring-

Specifies the Material Icons name for the selected state. Alternatively, use slot="selected-icon".

hrefhrefstring-

The URL for the hyperlink. If provided, the component is rendered as an <a> element and can use link-related attributes.

downloaddownloadstring-

Instructs the browser to download the linked URL.

Note: This is only available when href is specified.

targettarget'_blank' | '_parent' | '_self' | '_top'-

Defines where to open the linked URL. Possible values:

  • _blank: Opens in a new tab or window.
  • _parent: Opens in the parent browsing context or _self if no parent.
  • _self: Opens in the current browsing context. (Default).
  • _top: Opens in the topmost browsing context or _self if no ancestors.

Note: This is only available when href is specified.

relrel'alternate' | 'author' | 'bookmark' | 'external' | 'help' | 'license' | 'me' | 'next' | 'nofollow' | 'noreferrer' | 'opener' | 'prev' | 'search' | 'tag'-

Specifies the relationship of the linked URL as space-separated link types. Possible values:

  • alternate: Alternate versions of the current document.
  • author: The author of the current document or article.
  • bookmark: The permalink for the nearest ancestor section.
  • external: The referenced document is not part of the same site as the current document.
  • help: A link to context-sensitive help.
  • license: Indicates that the main content of the current document is covered by the copyright license described by the referenced document.
  • me: Indicates that the current document represents the person who owns the linked content.
  • next: Indicates that the current document is part of a series and the next document in the series is the referenced document.
  • nofollow: Indicates that the current document's original author or publisher does not endorse the referenced document.
  • noreferrer: No Referer header will be included. Also has the same effect as noopener.
  • opener: Creates an auxiliary browsing context if the hyperlink would otherwise create a top-level browsing context that is not an auxiliary browsing context (i.e., has "_blank" as target attribute value).
  • prev: Indicates that the current document is part of a series and the previous document in the series is the referenced document.
  • search: Links to a resource that can be used to search through the current document and its related pages.
  • tag: Gives a tag (identified by the given address) that applies to the current document.

Note: This is only available when href is specified.

autofocusautofocusbooleanfalse

Specifies that the element should be focused when the page loads.

tabindextabIndexnumber-

Defines the order in which the element receives focus when navigating with the Tab key.

disableddisabledbooleanfalse

Disables the element.

loadingloadingbooleanfalse

Indicates that the element is in a loading state.

namenamestring''

The button's name, which is submitted with form data.

Note: This is only available when href is not specified.

valuevaluestring''

The button's value, which is submitted with form data.

Note: This is only available when href is not specified.

typetype'submit' | 'reset' | 'button''button'

Defines the button's default behavior. The default is button. Possible values:

  • submit: Submits the form data to the server.
  • reset: Resets all the controls to their initial values.
  • button: No default behavior, does nothing when pressed by default.

Note: This is only available when href is not specified.

formformstring-

Associates the button with a <form> element. The value should be the id of a <form> in the same document. If not set, the button is associated with its parent <form>, if any.

This attribute allows button elements to be associated with <form>s anywhere in the document, not just inside a <form>.

Note: Only available when href is not specified.

formactionformActionstring-

Specifies the URL that processes the button's submitted information. Overrides the action attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".

formenctypeformEnctype'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain'-

Specifies the form data encoding method. Possible values:

  • application/x-www-form-urlencoded: Default if the attribute is not used.
  • multipart/form-data: Used for <input> elements with type set to file.
  • text/plain: For debugging, not for real form submission.

Overrides the enctype attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".

formmethodformMethod'post' | 'get'-

Specifies the HTTP method for form submission. Possible values:

  • post: Form data included in HTTP request body.
  • get: Form data appended to action URL.

Overrides the method attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".

formnovalidateformNoValidatebooleanfalse

Specifies that the form should not be validated on submission. Overrides the novalidate attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".

formtargetformTarget'_self' | '_blank' | '_parent' | '_top'-

Specifies where to display the form submission response. Possible values:

  • _self: Current browsing context. (Default).
  • _blank: New tab or window.
  • _parent: Parent browsing context or _self if no parent.
  • _top: Topmost browsing context or _self if no ancestors.

Overrides the target attribute of the button's form owner.

Note: Only available when href is not specified and type="submit".

validityValidityState-

A ValidityState object that represents the element's validity states.

validationMessagestring-

The element's validation message. This is empty if the element meets its constraints.

Methods

NameParametersReturns
click
void

Simulates a mouse click on the element.

focus
  • options: FocusOptions (Optional)
void

Sets focus on the element. An optional parameter can be an object with a preventScroll property. If preventScroll is set to true, the page will not scroll to bring the focused element into view.

blur
void

Removes focus from the element.

checkValidity
boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event and returns false. If it's valid, it returns true.

reportValidity
boolean

Checks the validity of the form field. If it's invalid, it triggers an invalid event, returns false, and displays a validation message. If it's valid, it returns true.

setCustomValidity
  • message: string
void

Sets a custom error message. If the text is non-empty, it indicates that the field is invalid.

Events

Name
focus

Emitted when the segmented button gains focus.

blur

Emitted when the segmented button loses focus.

invalid

Emitted when the form control's validity is checked and it doesn't meet the constraints.

Slots

Name
(default)

Text content.

icon

Left icon.

selected-icon

Icon for the selected state.

end-icon

Right icon.

CSS Parts

Name
button

Internal <button> or <a> element.

icon

Left icon.

selected-icon

Icon for the selected state.

end-icon

Right icon.

label

Text content.

loading

The <mdui-circular-progress> element for the loading state.

MDUIDocsEnglish简体中文LightDarkSystem
Preset Colors
Custom Color
Extract Color from Wallpaper
Select a Wallpaper
Getting Started
Introduction Installation Usage TypeScript Support IDE Support Localization Frequently Asked Questions
Styles
Dark Theme Dynamic Theme Typography Design Tokens
Frameworks
React Vue Angular
Components
Button ButtonIcon Fab SegmentedButton Chip Card Checkbox Radio Switch Slider RangeSlider List Collapse Tabs Dropdown Menu Select TextField LinearProgress CircularProgress Dialog Divider Avatar Badge Icon Tooltip Snackbar NavigationBar NavigationDrawer NavigationRail BottomAppBar TopAppBar Layout
Functions
JavaScript Library dialog alert confirm prompt snackbar getTheme setTheme getColorFromImage setColorScheme removeColorScheme loadLocale setLocale getLocale throttle observeResize breakpoint
Libraries
@mdui/icons