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

Variants

The variant attribute allows you to modify the shape of the select.

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.

Helper Text

The label attribute allows you to display label text above the select.

The placeholder attribute allows you to display placeholder text when no value is selected.

The helper attribute allows you to display helper text at the bottom of the select. Alternatively, use the helper slot to set helper text.

Read-Only State

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

Disabled State

To disable the select, add the disabled attribute.

Clearable

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

You can customize the clear button using the clear slot.

Dropdown Menu Position

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

Text Alignment

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

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.

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.

API

Properties

AttributePropertyReflectTypeDefault
variantvariant'filled' | 'outlined''filled'

Defines the select style. Possible values:

  • filled: Solid background, strong visual emphasis.
  • outlined: Bordered, less visual emphasis.
multiplemultiplebooleanfalse

Enables multiple selections.

namenamestring''

Name of the select, which is submitted with form data.

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

defaultValuestring | string[]''

Default selected value. Resets to this value when form is reset. Can only be set via JavaScript property.

labellabelstring-

Label text.

placeholderplaceholderstring-

Placeholder text.

helperhelperstring-

Helper text displayed below the select. Alternatively, use slot="helper".

clearableclearablebooleanfalse

Allows the select to be cleared.

clear-iconclearIconstring-

Material Icons name for the clear button displayed on the right of the select when clearable. Alternatively, use slot="clear-icon".

placementplacement'auto' | 'bottom' | 'top''auto'

Select placement. Possible values:

  • auto: Automatically determined.
  • bottom: Below the input.
  • top: Above the input.
end-alignedendAlignedbooleanfalse

Aligns text to the right.

prefixprefixstring-

Prefix text of the select. Displayed only when the select is focused or has a value. Alternatively, use slot="prefix".

suffixsuffixstring-

Suffix text of the select. Displayed only when the select is focused or has a value. Alternatively, use slot="suffix".

iconiconstring-

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

end-iconendIconstring-

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

error-iconerrorIconstring-

Material Icons name displayed on the right when form field validation fails. Alternatively, use slot="error-icon".

formformstring-

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

readonlyreadonlybooleanfalse

Makes the select read-only.

disableddisabledbooleanfalse

Disables the select.

requiredrequiredbooleanfalse

Requires a selection when the form is submitted.

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.

autofocusautofocusbooleanfalse

Determines if the element should be focused when the page loads.

tabindextabIndexnumber-

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

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.

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.

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