Select

The Select component is designed to present a list of options in a dropdown menu.

This guide focuses on the usage of the <mdui-select> component. For information on dropdown menu items, please refer to 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 is set to single-select. The value of the <mdui-select> component corresponds to the value of the currently selected <mdui-menu-item>.

To enable multi-select, 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 selections are enabled, the value of <mdui-select> is an array. This value can only be read and set using JavaScript properties.

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>

Code

Helper Text

The label attribute allows you to display label text 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>

Code

The placeholder attribute allows you 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>

Code

The helper attribute allows you to display helper text at the bottom of the select. Alternatively, use the helper slot to set 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>

Code

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>

Code

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>

Code

Clearable

The clearable attribute adds 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>

Code

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>

Code

Dropdown Menu Position

You can set the dropdown menu position using the placement attribute.

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>

Code

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>

Code

Prefix, Suffix, and Icons

You can add Material Icons to the left and right of the select by setting the icon and end-icon attributes. 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>

Code

You can add text to the left and right of the select by setting the prefix and suffix attributes. Alternatively, use the prefix and suffix slots to add text elements. This text is displayed 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>

Code

API

Properties

Attribute	Property	Type	Default
`variant`	`variant`	`'filled' \| 'outlined'`	`'filled'`
Defines the select style. Possible values: `filled`: Solid background, strong visual emphasis. `outlined`: Bordered, less 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; if set, it's an array of strings. HTML attributes can only set string values; array values must be set via JavaScript property.
	`defaultValue`	`string \| string[]`	`''`
Default selected value. Resets to this value when form is reset. Can only be set via JavaScript property.
`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`
Allows the select to be cleared.
`clear-icon`	`clearIcon`	`string`	-
Material Icons name for the clear button displayed on the right of the select 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. The value should be the `id` of a `<form>` in the same document. If not set, the select is associated with its parent `<form>`, if any. This attribute allows select elements to be associated with `<form>`s anywhere in the document, not just inside a `<form>`.
`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`	-
The element's validation message. This is empty if the element meets its constraints.
`autofocus`	`autofocus`	`boolean`	`false`
Determines if the element should be focused when the page loads.
`tabindex`	`tabIndex`	`number`	-
Specifies the order in which the element receives focus when navigating with the Tab key.

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

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 doesn't 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 multiselect 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.

Up Next

TextField