Select

The Select component presents options in a dropdown menu.

This guide focuses on the usage of the <mdui-select> component. For information on dropdown menu items, see the <mdui-menu-item> section.

Usage

Import the component:

import 'mdui/components/select.js';
import 'mdui/components/menu-item.js';

Import the TypeScript type:

import type { Select } from 'mdui/components/select.js';
import type { MenuItem } from 'mdui/components/menu-item.js';

Example:

Item 1

Item 2

<mdui-select value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

Examples

Multiple Selection

By default, the component allows only a single selection. The value of the <mdui-select> component corresponds to the value of the currently selected <mdui-menu-item>.

To allow multiple selections, add the multiple attribute. In this case, the value of <mdui-select> becomes an array containing the value properties of the currently selected <mdui-menu-item> components.

Note: When multiple selection is enabled, the value property of <mdui-select> is an array and can only be accessed and accessed and updated in JavaScript.

Item 1

Item 2

Item 3

<mdui-select multiple class="example-multiple">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
  <mdui-menu-item value="item-3">Item 3</mdui-menu-item>
</mdui-select>

<script>
  // Set default selection to item-1 and item-2
  const select = document.querySelector(".example-multiple");
  select.value = ["item-1", "item-2"];
</script>

Source

Helper Text

Use the label attribute to display a label above the select.

Item 1

Item 2

<mdui-select label="Text Field" value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

Source

Use the placeholder attribute to display placeholder text when no value is selected.

Item 1

Item 2

<mdui-select placeholder="Placeholder">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

Source

Use the helper attribute to display helper text at the bottom of the select. Alternatively, use the helper slot to provide helper text.

Item 1

Item 2

Item 1

Item 2

Supporting text

<mdui-select helper="Supporting text">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

<mdui-select>
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
  <span slot="helper" style="color: blue">Supporting text</span>
</mdui-select>

Source

Read-Only State

To make the select read-only, add the readonly attribute.

Item 1

Item 2

<mdui-select readonly value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

Source

Disabled State

To disable the select, add the disabled attribute.

Item 1

Item 2

<mdui-select disabled value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

Source

Clearable

The clearable attribute displays a clear button on the right when the select has a value.

Item 1

Item 2

<mdui-select clearable value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

Source

You can customize the clear button using the clear slot.

Item 1

Item 2

<mdui-select clearable value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
  <mdui-icon slot="clear" name="delete"></mdui-icon>
</mdui-select>

Source

Dropdown Menu Position

Use the placement attribute to set the dropdown menu position.

Item 1

Item 2

<mdui-select placement="top" value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

Source

Text Alignment

To align the text to the right, add the end-aligned attribute.

Item 1

Item 2

<mdui-select end-aligned value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

Source

Prefix, Suffix, and Icons

Use the icon and end-icon attributes to add Material Icons to the left and right of the select. Alternatively, use the icon and end-icon slots to add elements to the select.

Item 1

Item 2

Item 1

Item 2

<mdui-select value="item-1" icon="search" end-icon="mic">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

<br/><br/>

<mdui-select value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
  <mdui-button-icon slot="icon" icon="search"></mdui-button-icon>
  <mdui-button-icon slot="end-icon" icon="mic"></mdui-button-icon>
</mdui-select>

Source

Use the prefix and suffix attributes to add text to the left and right of the select. Alternatively, use the prefix and suffix slots to add text elements. They appear when the select is focused or has a value.

Item 1

Item 2

Item 1

Item 2

$ /100

<mdui-select value="item-1" prefix="$" suffix="/100">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

<br/><br/>

<mdui-select value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
  <span slot="prefix" style="color: blue">$</span>
  <span slot="suffix" style="color: blue">/100</span>
</mdui-select>

Source

API

Properties

Attribute	Property	Type	Default
`variant`	`variant`	`'filled' \| 'outlined'`	`'filled'`
Defines the select variant. Possible values: `filled`: Solid background with strong visual emphasis. `outlined`: Bordered with lighter visual emphasis.
`multiple`	`multiple`	`boolean`	`false`
Enables multiple selections.
`name`	`name`	`string`	`''`
Name of the select, which is submitted with form data.
`value`	`value`	`string \| string[]`	`''`
Value of the select, which is submitted with form data. If `multiple` is not set, the value is a string; otherwise, it is an array of strings. HTML attributes can only set string values; array values must be set via the JavaScript property.
	`defaultValue`	`string \| string[]`	`''`
Default selected value. The select resets to this value when the form is reset. JavaScript only.
`label`	`label`	`string`	-
Label text.
`placeholder`	`placeholder`	`string`	-
Placeholder text.
`helper`	`helper`	`string`	-
Helper text displayed below the select. Alternatively, use `slot="helper"`.
`clearable`	`clearable`	`boolean`	`false`
Makes the select clearable.
`clear-icon`	`clearIcon`	`string`	-
Material Icons name for the clear button displayed on the right when clearable. Alternatively, use `slot="clear-icon"`.
`placement`	`placement`	`'auto' \| 'bottom' \| 'top'`	`'auto'`
Select placement. Possible values: `auto`: Automatically determined. `bottom`: Below the input. `top`: Above the input.
`end-aligned`	`endAligned`	`boolean`	`false`
Aligns text to the right.
`prefix`	`prefix`	`string`	-
Prefix text of the select. Displayed only when the select is focused or has a value. Alternatively, use `slot="prefix"`.
`suffix`	`suffix`	`string`	-
Suffix text of the select. Displayed only when the select is focused or has a value. Alternatively, use `slot="suffix"`.
`icon`	`icon`	`string`	-
Material Icons name for the prefix icon. Alternatively, use `slot="icon"`.
`end-icon`	`endIcon`	`string`	-
Material Icons name for the suffix icon. Alternatively, use `slot="end-icon"`.
`error-icon`	`errorIcon`	`string`	-
Material Icons name displayed on the right when form field validation fails. Alternatively, use `slot="error-icon"`.
`form`	`form`	`string`	-
Associates the select with a `<form>` element. Set this to the `id` of a `<form>` in the same document. If omitted, the select uses its parent `<form>`, if any. This lets the select work with any form in the document, not just the one it is nested in.
`readonly`	`readonly`	`boolean`	`false`
Makes the select read-only.
`disabled`	`disabled`	`boolean`	`false`
Disables the select.
`required`	`required`	`boolean`	`false`
Requires a selection when the form is submitted.
	`validity`	`ValidityState`	-
A `ValidityState` object that represents the element's validity states.
	`validationMessage`	`string`	-
Validation message. Empty string when valid.
`autofocus`	`autofocus`	`boolean`	`false`
Whether the element is focused when the page loads.
`tabindex`	`tabIndex`	`number`	-
The element's tab order when navigating with the Tab key.

Methods

Name	Parameters	Returns
`checkValidity`		`boolean`
Checks the validity of the form field. If it is invalid, it triggers an `invalid` event and returns `false`. If valid, it returns `true`.
`reportValidity`		`boolean`
Checks the validity of the form field. If it is invalid, it triggers an `invalid` event, returns `false`, and displays a validation message. If valid, it returns `true`.
`setCustomValidity`	`message: string`	`void`
Sets a custom error message. If the message is non-empty, the field is considered invalid.
`click`		`void`
Simulates a mouse click on the element.
`focus`	`options: FocusOptions` (Optional)	`void`
Sets focus on the element. An optional object parameter may include 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.

Events

Name
`focus`
Emitted when the select gains focus.
`blur`
Emitted when the select loses focus.
`change`
Emitted when the selected value changes.
`invalid`
Emitted when the form control's validity is checked and it does not meet the constraints.
`clear`
Emitted when the clear button is clicked. Can be prevented with `event.preventDefault()`.

Slots

Name
(default)
`<mdui-menu-item>` elements.
`icon`
Left icon.
`end-icon`
Right icon.
`error-icon`
Right icon when validation fails.
`prefix`
Left text.
`suffix`
Right text.
`clear-button`
Clear button.
`clear-icon`
Icon in the clear button.
`helper`
Bottom helper text.

CSS Parts

Name
`chips`
Container for option chips when `multiple` is enabled.
`chip`
Individual chip representing each multi-select option.
`chip__button`
The `<button>` element within the chip.
`chip__label`
Text part of the chip.
`chip__delete-icon`
Delete icon within the chip.
`text-field`
Text field, i.e., `<mdui-text-field>` element.
`text-field__container`
Container for the text field.
`text-field__icon`
Icon within the text field.
`text-field__end-icon`
Right-side icon within the text field.
`text-field__error-icon`
Icon displayed in the text field upon validation failure.
`text-field__prefix`
Text on the left side of the text field.
`text-field__suffix`
Text on the right side of the text field.
`text-field__label`
Label text displayed above the text field.
`text-field__input`
The `<input>` element within the text field.
`text-field__clear-button`
Clear button within the text field.
`text-field__clear-icon`
Icon within the clear button of the text field.
`text-field__supporting`
Container for supporting information at the bottom of the text field, including helper and error messages.
`text-field__helper`
Helper text displayed at the bottom of the text field.
`text-field__error`
Error message displayed at the bottom of the text field.
`menu`
Dropdown menu, i.e., `<mdui-menu>` element.

RangeSlider

SegmentedButton