# Select Component

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>`](/en/docs/2/components/menu#menu-item-api) section.

## Usage {#usage}

Import the component:

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

Import the TypeScript type:

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

Example:

```html
<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 {#examples}

### Variants {#example-variant}

Use the `variant` attribute to change the select's shape.

```html
<mdui-select variant="filled" 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>

<mdui-select variant="outlined" 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>
```

### Multiple Selection {#example-multiple}

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>`](/en/docs/2/components/menu#menu-item-api).

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>`](/en/docs/2/components/menu#menu-item-api) 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.

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

### Helper Text {#example-helper-text}

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

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

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

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

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

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

### Read-Only State {#example-readonly}

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

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

### Disabled State {#example-disabled}

To disable the select, add the `disabled` attribute.

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

### Clearable {#example-clearable}

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

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

You can customize the clear button using the `clear` slot.

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

### Dropdown Menu Position {#example-placement}

Use the `placement` attribute to set the dropdown menu position.

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

### Text Alignment {#example-end-aligned}

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

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

### Prefix, Suffix, and Icons {#example-prefix-suffix}

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.

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

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.

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

## mdui-select API

### Properties

<table>
<thead>
  <tr>
    <th>Attribute</th>
    <th>Property</th>
    <th>Reflect</th>
    <th>Type</th>
    <th>Default</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>variant</td>
    <td>variant</td>
    <td>true</td>
    <td>&#39;filled&#39; | &#39;outlined&#39;</td>
    <td>'filled'</td>
    <td><p>Defines the select variant. Possible values:</p>
<ul>
<li><code>filled</code>: Solid background with strong visual emphasis.</li>
<li><code>outlined</code>: Bordered with lighter visual emphasis.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>multiple</td>
    <td>multiple</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Enables multiple selections.</p>
</td>
  </tr>
  <tr>
    <td>name</td>
    <td>name</td>
    <td>true</td>
    <td>string</td>
    <td>''</td>
    <td><p>Name of the select, which is submitted with form data.</p>
</td>
  </tr>
  <tr>
    <td>value</td>
    <td>value</td>
    <td>false</td>
    <td>string | string[]</td>
    <td>''</td>
    <td><p>Value of the select, which is submitted with form data.</p>
<p>If <code>multiple</code> 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.</p>
</td>
  </tr>
  <tr>
    <td>undefined</td>
    <td>defaultValue</td>
    <td>false</td>
    <td>string | string[]</td>
    <td>''</td>
    <td><p>Default selected value. The select resets to this value when the form is reset. JavaScript only.</p>
</td>
  </tr>
  <tr>
    <td>label</td>
    <td>label</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Label text.</p>
</td>
  </tr>
  <tr>
    <td>placeholder</td>
    <td>placeholder</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Placeholder text.</p>
</td>
  </tr>
  <tr>
    <td>helper</td>
    <td>helper</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Helper text displayed below the select. Alternatively, use <code>slot=&quot;helper&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>clearable</td>
    <td>clearable</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Makes the select clearable.</p>
</td>
  </tr>
  <tr>
    <td>clear-icon</td>
    <td>clearIcon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Material Icons name for the clear button displayed on the right when clearable. Alternatively, use <code>slot=&quot;clear-icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>placement</td>
    <td>placement</td>
    <td>true</td>
    <td>&#39;auto&#39; | &#39;bottom&#39; | &#39;top&#39;</td>
    <td>'auto'</td>
    <td><p>Select placement. Possible values:</p>
<ul>
<li><code>auto</code>: Automatically determined.</li>
<li><code>bottom</code>: Below the input.</li>
<li><code>top</code>: Above the input.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>end-aligned</td>
    <td>endAligned</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Aligns text to the right.</p>
</td>
  </tr>
  <tr>
    <td>prefix</td>
    <td>prefix</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Prefix text of the select. Displayed only when the select is focused or has a value. Alternatively, use <code>slot=&quot;prefix&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>suffix</td>
    <td>suffix</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Suffix text of the select. Displayed only when the select is focused or has a value. Alternatively, use <code>slot=&quot;suffix&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td>icon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Material Icons name for the prefix icon. Alternatively, use <code>slot=&quot;icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>end-icon</td>
    <td>endIcon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Material Icons name for the suffix icon. Alternatively, use <code>slot=&quot;end-icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>error-icon</td>
    <td>errorIcon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Material Icons name displayed on the right when form field validation fails. Alternatively, use <code>slot=&quot;error-icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>form</td>
    <td>form</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Associates the select with a <code>&lt;form&gt;</code> element. Set this to the <code>id</code> of a <code>&lt;form&gt;</code> in the same document. If omitted, the select uses its parent <code>&lt;form&gt;</code>, if any.</p>
<p>This lets the select work with any form in the document, not just the one it is nested in.</p>
</td>
  </tr>
  <tr>
    <td>readonly</td>
    <td>readonly</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Makes the select read-only.</p>
</td>
  </tr>
  <tr>
    <td>disabled</td>
    <td>disabled</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Disables the select.</p>
</td>
  </tr>
  <tr>
    <td>required</td>
    <td>required</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Requires a selection when the form is submitted.</p>
</td>
  </tr>
  <tr>
    <td>undefined</td>
    <td>validity</td>
    <td>false</td>
    <td>ValidityState</td>
    <td></td>
    <td><p>A <a href="https://developer.mozilla.org/en-US/docs/Web/API/ValidityState" target="_blank" rel="noopener nofollow"><code>ValidityState</code></a> object that represents the element&#39;s validity states.</p>
</td>
  </tr>
  <tr>
    <td>undefined</td>
    <td>validationMessage</td>
    <td>false</td>
    <td>string</td>
    <td></td>
    <td><p>Validation message. Empty string when valid.</p>
</td>
  </tr>
  <tr>
    <td>autofocus</td>
    <td>autofocus</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Whether the element is focused when the page loads.</p>
</td>
  </tr>
  <tr>
    <td>tabindex</td>
    <td>tabIndex</td>
    <td>false</td>
    <td>number</td>
    <td></td>
    <td><p>The element&#39;s tab order when navigating with the Tab key.</p>
</td>
  </tr>
</tbody>
</table>

### Methods

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>checkValidity(): boolean</td>
    <td><p>Checks the validity of the form field. If it is invalid, it triggers an <code>invalid</code> event and returns <code>false</code>. If valid, it returns <code>true</code>.</p>
</td>
  </tr>
  <tr>
    <td>reportValidity(): boolean</td>
    <td><p>Checks the validity of the form field. If it is invalid, it triggers an <code>invalid</code> event, returns <code>false</code>, and displays a validation message. If valid, it returns <code>true</code>.</p>
</td>
  </tr>
  <tr>
    <td>setCustomValidity(message: string): void</td>
    <td><p>Sets a custom error message. If the message is non-empty, the field is considered invalid.</p>
</td>
  </tr>
  <tr>
    <td>click(): void</td>
    <td><p>Simulates a mouse click on the element.</p>
</td>
  </tr>
  <tr>
    <td>focus(options?: FocusOptions): void</td>
    <td><p>Sets focus on the element. An optional object parameter may include a <code>preventScroll</code> property. If <code>preventScroll</code> is set to <code>true</code>, the page will not scroll to bring the focused element into view.</p>
</td>
  </tr>
  <tr>
    <td>blur(): void</td>
    <td><p>Removes focus from the element.</p>
</td>
  </tr>
</tbody>
</table>

### Events

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>focus</td>
    <td><p>Emitted when the select gains focus.</p>
</td>
  </tr>
  <tr>
    <td>blur</td>
    <td><p>Emitted when the select loses focus.</p>
</td>
  </tr>
  <tr>
    <td>change</td>
    <td><p>Emitted when the selected value changes.</p>
</td>
  </tr>
  <tr>
    <td>invalid</td>
    <td><p>Emitted when the form control&#39;s validity is checked and it does not meet the constraints.</p>
</td>
  </tr>
  <tr>
    <td>clear</td>
    <td><p>Emitted when the clear button is clicked. Can be prevented with <code>event.preventDefault()</code>.</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(default)</td>
    <td><p><code>&lt;mdui-menu-item&gt;</code> elements.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Left icon.</p>
</td>
  </tr>
  <tr>
    <td>end-icon</td>
    <td><p>Right icon.</p>
</td>
  </tr>
  <tr>
    <td>error-icon</td>
    <td><p>Right icon when validation fails.</p>
</td>
  </tr>
  <tr>
    <td>prefix</td>
    <td><p>Left text.</p>
</td>
  </tr>
  <tr>
    <td>suffix</td>
    <td><p>Right text.</p>
</td>
  </tr>
  <tr>
    <td>clear-button</td>
    <td><p>Clear button.</p>
</td>
  </tr>
  <tr>
    <td>clear-icon</td>
    <td><p>Icon in the clear button.</p>
</td>
  </tr>
  <tr>
    <td>helper</td>
    <td><p>Bottom helper text.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Parts

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>chips</td>
    <td><p>Container for option chips when <code>multiple</code> is enabled.</p>
</td>
  </tr>
  <tr>
    <td>chip</td>
    <td><p>Individual chip representing each multi-select option.</p>
</td>
  </tr>
  <tr>
    <td>chip__button</td>
    <td><p>The <code>&lt;button&gt;</code> element within the chip.</p>
</td>
  </tr>
  <tr>
    <td>chip__label</td>
    <td><p>Text part of the chip.</p>
</td>
  </tr>
  <tr>
    <td>chip__delete-icon</td>
    <td><p>Delete icon within the chip.</p>
</td>
  </tr>
  <tr>
    <td>text-field</td>
    <td><p>Text field, i.e., <a href="/en/docs/2/components/text-field"><code>&lt;mdui-text-field&gt;</code></a> element.</p>
</td>
  </tr>
  <tr>
    <td>text-field__container</td>
    <td><p>Container for the text field.</p>
</td>
  </tr>
  <tr>
    <td>text-field__icon</td>
    <td><p>Icon within the text field.</p>
</td>
  </tr>
  <tr>
    <td>text-field__end-icon</td>
    <td><p>Right-side icon within the text field.</p>
</td>
  </tr>
  <tr>
    <td>text-field__error-icon</td>
    <td><p>Icon displayed in the text field upon validation failure.</p>
</td>
  </tr>
  <tr>
    <td>text-field__prefix</td>
    <td><p>Text on the left side of the text field.</p>
</td>
  </tr>
  <tr>
    <td>text-field__suffix</td>
    <td><p>Text on the right side of the text field.</p>
</td>
  </tr>
  <tr>
    <td>text-field__label</td>
    <td><p>Label text displayed above the text field.</p>
</td>
  </tr>
  <tr>
    <td>text-field__input</td>
    <td><p>The <code>&lt;input&gt;</code> element within the text field.</p>
</td>
  </tr>
  <tr>
    <td>text-field__clear-button</td>
    <td><p>Clear button within the text field.</p>
</td>
  </tr>
  <tr>
    <td>text-field__clear-icon</td>
    <td><p>Icon within the clear button of the text field.</p>
</td>
  </tr>
  <tr>
    <td>text-field__supporting</td>
    <td><p>Container for supporting information at the bottom of the text field, including helper and error messages.</p>
</td>
  </tr>
  <tr>
    <td>text-field__helper</td>
    <td><p>Helper text displayed at the bottom of the text field.</p>
</td>
  </tr>
  <tr>
    <td>text-field__error</td>
    <td><p>Error message displayed at the bottom of the text field.</p>
</td>
  </tr>
  <tr>
    <td>menu</td>
    <td><p>Dropdown menu, i.e., <a href="/en/docs/2/components/menu"><code>&lt;mdui-menu&gt;</code></a> element.</p>
</td>
  </tr>
</tbody>
</table>