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>

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>.

Day

Week

Month

Day

Week

Month

<mdui-segmented-button-group selects="single">
  <mdui-segmented-button value="day">Day</mdui-segmented-button>
  <mdui-segmented-button value="week">Week</mdui-segmented-button>
  <mdui-segmented-button value="month">Month</mdui-segmented-button>
</mdui-segmented-button-group>

<mdui-segmented-button-group selects="single" value="week">
  <mdui-segmented-button value="day">Day</mdui-segmented-button>
  <mdui-segmented-button value="week">Week</mdui-segmented-button>
  <mdui-segmented-button value="month">Month</mdui-segmented-button>
</mdui-segmented-button-group>

Code

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.

Day

Week

Month

Day

Week

Month

<mdui-segmented-button-group selects="multiple">
  <mdui-segmented-button value="day">Day</mdui-segmented-button>
  <mdui-segmented-button value="week">Week</mdui-segmented-button>
  <mdui-segmented-button value="month">Month</mdui-segmented-button>
</mdui-segmented-button-group>

<mdui-segmented-button-group selects="multiple" class="demo-multiple">
  <mdui-segmented-button value="day">Day</mdui-segmented-button>
  <mdui-segmented-button value="week">Week</mdui-segmented-button>
  <mdui-segmented-button value="month">Month</mdui-segmented-button>
</mdui-segmented-button-group>

<script>
  // Set the default selection to week and month
  const group = document.querySelector(".demo-multiple");
  group.value = ["week", "month"];
</script>

Code

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.

Day

Week

Month

<mdui-segmented-button-group>
  <mdui-segmented-button icon="search">Day</mdui-segmented-button>
  <mdui-segmented-button end-icon="arrow_forward">Week</mdui-segmented-button>
  <mdui-segmented-button>
    Month
    <mdui-icon slot="icon" name="downloading"></mdui-icon>
    <mdui-icon slot="end-icon" name="attach_file"></mdui-icon>
  </mdui-segmented-button>
</mdui-segmented-button-group>

Code

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.

Day

Week

<mdui-segmented-button-group selects="multiple">
  <mdui-segmented-button value="day" selected-icon="cloud_done">Day</mdui-segmented-button>
  <mdui-segmented-button value="week">
    <mdui-icon slot="selected-icon" name="cloud_done"></mdui-icon>
    Week
  </mdui-segmented-button>
</mdui-segmented-button-group>

Code

Link

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.

Link

Week

Month

<mdui-segmented-button-group>
  <mdui-segmented-button href="https://www.mdui.org" target="_blank">Link</mdui-segmented-button>
  <mdui-segmented-button>Week</mdui-segmented-button>
  <mdui-segmented-button>Month</mdui-segmented-button>
</mdui-segmented-button-group>

Code

Disabled and Loading States

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

Day

Week

Month

<mdui-segmented-button-group disabled>
  <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>

Code

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.

Day

Week

Month

Year

<mdui-segmented-button-group>
  <mdui-segmented-button>Day</mdui-segmented-button>
  <mdui-segmented-button disabled>Week</mdui-segmented-button>
  <mdui-segmented-button loading>Month</mdui-segmented-button>
  <mdui-segmented-button disabled loading>Year</mdui-segmented-button>
</mdui-segmented-button-group>

Code

`mdui-segmented-button-group` API

Properties

Attribute	Property	Type	Default
`full-width`	`fullWidth`	`boolean`	`false`
If set, the segmented button group will fill the width of its parent element.
`selects`	`selects`	`'single' \| 'multiple'`	-
Defines selectable states. Default is non-selectable. Possible values: `single`: Only one can be selected. `multiple`: Multiple selections are allowed.
`disabled`	`disabled`	`boolean`	`false`
Disables the segmented button group when set.
`required`	`required`	`boolean`	`false`
Requires a selection when the form is submitted.
`form`	`form`	`string`	-
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>`.
`name`	`name`	`string`	`''`
The name of the segmented button group, which is submitted with form data.
`value`	`value`	`string \| 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.
	`defaultValue`	`string \| string[]`	`''`
The default selected value. Resets to this state when the form is reset. This value can only be set via JavaScript property.
	`validity`	`ValidityState`	-
A `ValidityState` object that represents the element's validity states.
	`validationMessage`	`string`	-
The element's validation message. This is empty if the element meets its constraints.

Methods

Name	Parameters	Returns
`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

Attribute	Property	Type	Default
`icon`	`icon`	`string`	-
Specifies the Material Icons name for the left icon. Alternatively, use `slot="icon"`.
`end-icon`	`endIcon`	`string`	-
Specifies the Material Icons name for the right icon. Alternatively, use `slot="end-icon"`.
`selected-icon`	`selectedIcon`	`string`	-
Specifies the Material Icons name for the selected state. Alternatively, use `slot="selected-icon"`.
`href`	`href`	`string`	-
The URL for the hyperlink. If provided, the component is rendered as an `<a>` element and can use link-related attributes.
`download`	`download`	`string`	-
Instructs the browser to download the linked URL. Note: This is only available when `href` is specified.
`target`	`target`	`'_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.
`rel`	`rel`	`'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.
`autofocus`	`autofocus`	`boolean`	`false`
Specifies that the element should be focused when the page loads.
`tabindex`	`tabIndex`	`number`	-
Defines the order in which the element receives focus when navigating with the Tab key.
`disabled`	`disabled`	`boolean`	`false`
Disables the element.
`loading`	`loading`	`boolean`	`false`
Indicates that the element is in a loading state.
`name`	`name`	`string`	`''`
The button's name, which is submitted with form data. Note: This is only available when `href` is not specified.
`value`	`value`	`string`	`''`
The button's value, which is submitted with form data. Note: This is only available when `href` is not specified.
`type`	`type`	`'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.
`form`	`form`	`string`	-
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.
`formaction`	`formAction`	`string`	-
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"`.
`formenctype`	`formEnctype`	`'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"`.
`formmethod`	`formMethod`	`'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"`.
`formnovalidate`	`formNoValidate`	`boolean`	`false`
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"`.
`formtarget`	`formTarget`	`'_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"`.
	`validity`	`ValidityState`	-
A `ValidityState` object that represents the element's validity states.
	`validationMessage`	`string`	-
The element's validation message. This is empty if the element meets its constraints.

Methods

Name	Parameters	Returns
`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.

Select

Up Next

Slider

SegmentedButton

Usage

Examples

Full Width

Single Selection

Multiple Selection

Icons

Link

Disabled and Loading States

`mdui-segmented-button-group` API

Properties

Methods

Events

Slots

CSS Custom Properties

`mdui-segmented-button` API

Properties

Methods

Events

Slots

CSS Parts