# Select Menus
MDC Select provides Material Design single-option select menus, using the MDC menu.
The Select component is fully accessible, and supports RTL rendering.
## Important Changes
Select is currently being updated to use the new List implementation. For now,
please continue to use the old implementation (`mdc-deprecated-list` and
associated DOM/classes) instead of the new one (`mdc-list`).
See the [List documentation](../mdc-list/README.md) for more information.
## Design & API Documentation
## Installation
```
npm install @material/select
```
## Basic Usage
The select uses an [`MDCMenu`](../mdc-menu) component instance to contain the list of options, but uses the
`data-value` attribute instead of `value` to represent the options' values.
> _NOTE_: The `data-value` attribute _must_ be present on each option.
The select requires that you set the `width` of the `mdc-select` element. This is best done through the use of another class (e.g. `demo-width-class` in the example HTML and CSS below).
### HTML
The HTML for the select component follows the WAI-ARIA recommendations for
[Collapsible Dropdown Listboxes](https://www.w3.org/TR/wai-aria-practices/examples/listbox/listbox-collapsible.html) in order to meet WCAG and ARIA accessibility standards, and to be compatible with assistive technology like screen readers.
The following example applies ARIA attributes that provide the semantic structure required for assistive technology:
```html
Pick a Food Group
Bread, Cereal, Rice, and Pasta
Vegetables
Fruit
```
> _NOTE_: The menu width matches the width of the select by default. To set
menu to its natural width, remove `mdc-menu-surface--fullwidth` from the menu
surface.
### Styles
When using the select, you will also need to load the Menu and List components' styles.
```scss
@use "@material/list/mdc-list";
@use "@material/menu-surface/mdc-menu-surface";
@use "@material/menu/mdc-menu";
@use "@material/select/styles";
.demo-width-class {
width: 400px;
}
```
### Theming
```scss
@use '@material/select';
.my-demo-select {
@include select.filled-density(-2);
}
```
### JavaScript Instantiation
```js
import {MDCSelect} from '@material/select';
const select = new MDCSelect(document.querySelector('.mdc-select'));
select.listen('MDCSelect:change', () => {
alert(`Selected option at index ${select.selectedIndex} with value "${select.value}"`);
});
```
See [Importing the JS component](../../docs/importing-js.md) for more information on how to import JavaScript.
## Variants
### Outlined Select
The Select Outlined variant uses the `mdc-notched-outline` in place of the `mdc-line-ripple` element and adds the
`mdc-select--outlined` modifier class on the root element. All other elements for each type of select remain the
same.
```html
Pick a Food Group
...
```
### Additional Information
#### Select with hidden input (for HTML forms)
For convenient submission of Select's value in HTML forms, a hidden input
element may be added under the root element. The component will synchronize its
value with that of the hidden input.
```html
```
#### Select with pre-selected option
To indicate a select component that has a pre-selected value, use the `mdc-deprecated-list-item--selected` class
to set the selected item. The select also needs the text from the selected element copied to the
`mdc-select__selected-text` element.
```html
Pick a Food GroupVegetables
Bread, Cereal, Rice, and Pasta
Vegetables
Fruit
```
#### Using the floating label as the placeholder
Leave the `mdc-select__selected-text` element empty and don't specify an element as selected.
If leaving the field empty should be a valid option, include an `mdc-deprecated-list-item` element at the beginning of
the list with an empty `data-value` attribute.
```html
```
#### Required select
To style a select menu as required and enable validation, add the `mdc-select--required` class to the `mdc-select` element
and set the `aria-required` attribute on the `mdc-select__anchor` element to be `"true"`.
```html
Pick a Food Group
...
```
> _NOTE_: To programmatically set a select as required, use the `required` property in the `MDCSelect` API.
#### Disabled select
Add the `mdc-select--disabled` class to the `mdc-select` element, set the
`aria-disabled` attribute on the `mdc-select__selected-text` element to
be `"true"`, and set the disabled attribute any hidden input element.
```html
Pick a Food Group
...
```
> _NOTE_: To programmatically set a select as disabled, use the `disabled` property in the `MDCSelect` API.
#### Disabled options
Add the `mdc-deprecated-list-item--disabled` class to list items that are disabled.
Disabled list items are removed from the list items index and are ignored entirely. You cannot
programmatically select a disabled list item.
```html
...
Bread, Cereal, Rice, and Pasta
Vegetables
Fruit
```
### Select with Helper Text
The helper text provides supplemental information and/or validation messages to users. It appears when the select
element is focused and disappears on blur by default, or it can be persistent.
See [here](helper-text/) for more information on using helper text.
### Select with Leading Icons
Leading icons can be added within the default or outlined variant of MDC Select as visual indicators as
well as interaction targets. See [here](icon/) for more information on using icons.
### Select with No Label
A label is not required if a separate, adjacent label is provided elsewhere. To correctly style
MDC Select without a label, add the class `mdc-select--no-label` and remove the label from the
structure.
#### Filled
```html
Bread, Cereal, Rice, and Pasta
Vegetables
Fruit
```
#### Outlined
```html
...
```
## Style Customization
#### CSS Classes
| Class | Description |
| --- | --- |
| `mdc-select` | Mandatory. |
| `mdc-select__anchor` | Mandatory. This element should be placed within the `mdc-select` element. |
| `mdc-select__menu` | Mandatory. This class should be placed on the `mdc-menu` element within the `mdc-select` element. |
| `mdc-select__dropdown-icon` | Mandatory. Should be placed on an `i` element within the `mdc-select__anchor` element. Used for the dropdown arrow svg and animation.
| `mdc-select__selected-text-container` | Mandatory. This class wraps the `mdc-select__selected-text` and facilitates `text-overflow: ellipsis` on it. |
| `mdc-select__selected-text` | Mandatory. This class should be placed on a `span` within the `mdc-select__anchor` element. |
| `mdc-select__icon` | Optional. Should be placed on an `i` or `svg` element within the `mdc-select__anchor` element. Used for the leading icon.
| `mdc-select--activated` | Optional. Styles the activated state of select. This class will be added automatically when menu is opened.
| `mdc-select--disabled` | Optional. Styles the select as disabled. This class should be applied to the root element when the `disabled` attribute is applied to the `