1 |
|
2 | title: "Select Menus"
|
3 | layout: detail
|
4 | section: components
|
5 | iconId: menu
|
6 | path: /catalog/input-controls/select-menus/
|
7 | -->
|
8 |
|
9 | # Select Menus
|
10 |
|
11 | MDC Select provides Material Design single-option select menus, using the MDC menu.
|
12 | The Select component is fully accessible, and supports RTL rendering.
|
13 |
|
14 | ## Important Changes
|
15 |
|
16 | Select is currently being updated to use the new List implementation. For now,
|
17 | please continue to use the old implementation (`mdc-deprecated-list` and
|
18 | associated DOM/classes) instead of the new one (`mdc-list`).
|
19 |
|
20 | See the [List documentation](../mdc-list/README.md) for more information.
|
21 |
|
22 | ## Design & API Documentation
|
23 |
|
24 | <ul class="icon-list">
|
25 | <li class="icon-list-item icon-list-item--spec">
|
26 | <a href="https://material.io/go/design-text-fields">Material Design guidelines: Text Fields</a>
|
27 | </li>
|
28 | <li class="icon-list-item icon-list-item--link">
|
29 | <a href="https://material-components.github.io/material-components-web-catalog/#/component/select">Demo</a>
|
30 | </li>
|
31 | </ul>
|
32 |
|
33 | ## Installation
|
34 |
|
35 | ```
|
36 | npm install @material/select
|
37 | ```
|
38 |
|
39 | ## Basic Usage
|
40 |
|
41 | The select uses an [`MDCMenu`](../mdc-menu) component instance to contain the list of options, but uses the
|
42 | `data-value` attribute instead of `value` to represent the options' values.
|
43 |
|
44 | > _NOTE_: The `data-value` attribute _must_ be present on each option.
|
45 |
|
46 | 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).
|
47 |
|
48 | ### HTML
|
49 |
|
50 | The HTML for the select component follows the WAI-ARIA recommendations for
|
51 | [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.
|
52 |
|
53 | The following example applies ARIA attributes that provide the semantic structure required for assistive technology:
|
54 |
|
55 | ```html
|
56 | <div class="mdc-select mdc-select--filled demo-width-class">
|
57 | <div class="mdc-select__anchor"
|
58 | role="button"
|
59 | aria-haspopup="listbox"
|
60 | aria-expanded="false"
|
61 | aria-labelledby="demo-label demo-selected-text">
|
62 | <span class="mdc-select__ripple"></span>
|
63 | <span id="demo-label" class="mdc-floating-label">Pick a Food Group</span>
|
64 | <span class="mdc-select__selected-text-container">
|
65 | <span id="demo-selected-text" class="mdc-select__selected-text"></span>
|
66 | </span>
|
67 | <span class="mdc-select__dropdown-icon">
|
68 | <svg
|
69 | class="mdc-select__dropdown-icon-graphic"
|
70 | viewBox="7 10 10 5" focusable="false">
|
71 | <polygon
|
72 | class="mdc-select__dropdown-icon-inactive"
|
73 | stroke="none"
|
74 | fill-rule="evenodd"
|
75 | points="7 10 12 15 17 10">
|
76 | </polygon>
|
77 | <polygon
|
78 | class="mdc-select__dropdown-icon-active"
|
79 | stroke="none"
|
80 | fill-rule="evenodd"
|
81 | points="7 15 12 10 17 15">
|
82 | </polygon>
|
83 | </svg>
|
84 | </span>
|
85 | <span class="mdc-line-ripple"></span>
|
86 | </div>
|
87 |
|
88 | <div class="mdc-select__menu mdc-menu mdc-menu-surface mdc-menu-surface--fullwidth">
|
89 | <ul class="mdc-deprecated-list" role="listbox" aria-label="Food picker listbox">
|
90 | <li class="mdc-deprecated-list-item mdc-deprecated-list-item--selected" aria-selected="true" data-value="" role="option">
|
91 | <span class="mdc-deprecated-list-item__ripple"></span>
|
92 | </li>
|
93 | <li class="mdc-deprecated-list-item" aria-selected="false" data-value="grains" role="option">
|
94 | <span class="mdc-deprecated-list-item__ripple"></span>
|
95 | <span class="mdc-deprecated-list-item__text">
|
96 | Bread, Cereal, Rice, and Pasta
|
97 | </span>
|
98 | </li>
|
99 | <li class="mdc-deprecated-list-item mdc-deprecated-list-item--disabled" aria-selected="false" data-value="vegetables" aria-disabled="true" role="option">
|
100 | <span class="mdc-deprecated-list-item__ripple"></span>
|
101 | <span class="mdc-deprecated-list-item__text">
|
102 | Vegetables
|
103 | </span>
|
104 | </li>
|
105 | <li class="mdc-deprecated-list-item" aria-selected="false" data-value="fruit" role="option">
|
106 | <span class="mdc-deprecated-list-item__ripple"></span>
|
107 | <span class="mdc-deprecated-list-item__text">
|
108 | Fruit
|
109 | </span>
|
110 | </li>
|
111 | </ul>
|
112 | </div>
|
113 | </div>
|
114 | ```
|
115 |
|
116 | > _NOTE_: The menu width matches the width of the select by default. To set
|
117 | menu to its natural width, remove `mdc-menu-surface--fullwidth` from the menu
|
118 | surface.
|
119 |
|
120 | ### Styles
|
121 |
|
122 | When using the select, you will also need to load the Menu and List components' styles.
|
123 |
|
124 | ```scss
|
125 | @use "@material/list/mdc-list";
|
126 | @use "@material/menu-surface/mdc-menu-surface";
|
127 | @use "@material/menu/mdc-menu";
|
128 | @use "@material/select/styles";
|
129 |
|
130 | .demo-width-class {
|
131 | width: 400px;
|
132 | }
|
133 | ```
|
134 |
|
135 | ### Theming
|
136 |
|
137 | ```scss
|
138 | @use '@material/select';
|
139 |
|
140 | .my-demo-select {
|
141 | @include select.filled-density(-2);
|
142 | }
|
143 | ```
|
144 |
|
145 | ### JavaScript Instantiation
|
146 |
|
147 | ```js
|
148 | import {MDCSelect} from '@material/select';
|
149 |
|
150 | const select = new MDCSelect(document.querySelector('.mdc-select'));
|
151 |
|
152 | select.listen('MDCSelect:change', () => {
|
153 | alert(`Selected option at index ${select.selectedIndex} with value "${select.value}"`);
|
154 | });
|
155 | ```
|
156 |
|
157 | See [Importing the JS component](../../docs/importing-js.md) for more information on how to import JavaScript.
|
158 |
|
159 | ## Variants
|
160 |
|
161 | ### Outlined Select
|
162 |
|
163 | The Select Outlined variant uses the `mdc-notched-outline` in place of the `mdc-line-ripple` element and adds the
|
164 | `mdc-select--outlined` modifier class on the root element. All other elements for each type of select remain the
|
165 | same.
|
166 |
|
167 | ```html
|
168 | <div class="mdc-select mdc-select--outlined">
|
169 | <div class="mdc-select__anchor" aria-labelledby="outlined-select-label">
|
170 | <span class="mdc-notched-outline">
|
171 | <span class="mdc-notched-outline__leading"></span>
|
172 | <span class="mdc-notched-outline__notch">
|
173 | <span id="outlined-select-label" class="mdc-floating-label">Pick a Food Group</span>
|
174 | </span>
|
175 | <span class="mdc-notched-outline__trailing"></span>
|
176 | </span>
|
177 | <span class="mdc-select__selected-text-container">
|
178 | <span id="demo-selected-text" class="mdc-select__selected-text"></span>
|
179 | </span>
|
180 | <span class="mdc-select__dropdown-icon">
|
181 | <svg
|
182 | class="mdc-select__dropdown-icon-graphic"
|
183 | viewBox="7 10 10 5" focusable="false">
|
184 | <polygon
|
185 | class="mdc-select__dropdown-icon-inactive"
|
186 | stroke="none"
|
187 | fill-rule="evenodd"
|
188 | points="7 10 12 15 17 10">
|
189 | </polygon>
|
190 | <polygon
|
191 | class="mdc-select__dropdown-icon-active"
|
192 | stroke="none"
|
193 | fill-rule="evenodd"
|
194 | points="7 15 12 10 17 15">
|
195 | </polygon>
|
196 | </svg>
|
197 | </span>
|
198 | </div>
|
199 |
|
200 | <!-- Other elements from the select remain. -->
|
201 | <div class="mdc-select__menu mdc-menu mdc-menu-surface mdc-menu-surface--fullwidth">...</div>
|
202 | </div>
|
203 | ```
|
204 |
|
205 | ### Additional Information
|
206 |
|
207 | #### Select with hidden input (for HTML forms)
|
208 |
|
209 | For convenient submission of Select's value in HTML forms, a hidden input
|
210 | element may be added under the root element. The component will synchronize its
|
211 | value with that of the hidden input.
|
212 |
|
213 | ```html
|
214 | <div class="mdc-select mdc-select--filled demo-width-class">
|
215 | <input type="hidden" name="demo-input">
|
216 | <div class="mdc-select__anchor">
|
217 | <!-- Rest of component omitted for brevity -->
|
218 | </div>
|
219 | </div>
|
220 |
|
221 | ```
|
222 |
|
223 | #### Select with pre-selected option
|
224 |
|
225 | To indicate a select component that has a pre-selected value, use the `mdc-deprecated-list-item--selected` class
|
226 | to set the selected item. The select also needs the text from the selected element copied to the
|
227 | `mdc-select__selected-text` element.
|
228 |
|
229 | ```html
|
230 | <div class="mdc-select mdc-select--filled demo-width-class">
|
231 | <div class="mdc-select__anchor">
|
232 | <span class="mdc-select__ripple"></span>
|
233 | <span class="mdc-floating-label mdc-floating-label--float-above">Pick a Food Group</span>
|
234 | <span class="mdc-select__selected-text-container">
|
235 | <span class="mdc-select__selected-text">Vegetables</span>
|
236 | </span>
|
237 | <span class="mdc-select__dropdown-icon">
|
238 | <svg
|
239 | class="mdc-select__dropdown-icon-graphic"
|
240 | viewBox="7 10 10 5" focusable="false">
|
241 | <polygon
|
242 | class="mdc-select__dropdown-icon-inactive"
|
243 | stroke="none"
|
244 | fill-rule="evenodd"
|
245 | points="7 10 12 15 17 10">
|
246 | </polygon>
|
247 | <polygon
|
248 | class="mdc-select__dropdown-icon-active"
|
249 | stroke="none"
|
250 | fill-rule="evenodd"
|
251 | points="7 15 12 10 17 15">
|
252 | </polygon>
|
253 | </svg>
|
254 | </span>
|
255 | <span class="mdc-line-ripple"></span>
|
256 | </div>
|
257 |
|
258 | <div class="mdc-select__menu demo-width-class mdc-menu mdc-menu-surface">
|
259 | <ul class="mdc-deprecated-list">
|
260 | <li class="mdc-deprecated-list-item" data-value="">
|
261 | <span class="mdc-deprecated-list-item__ripple"></span>
|
262 | </li>
|
263 | <li class="mdc-deprecated-list-item" data-value="grains">
|
264 | <span class="mdc-deprecated-list-item__ripple"></span>
|
265 | <span class="mdc-deprecated-list-item__text">Bread, Cereal, Rice, and Pasta</span>
|
266 | </li>
|
267 | <li class="mdc-deprecated-list-item mdc-deprecated-list-item--selected" data-value="vegetables" aria-selected="true">
|
268 | <span class="mdc-deprecated-list-item__ripple"></span>
|
269 | <span class="mdc-deprecated-list-item__text">Vegetables</span>
|
270 | </li>
|
271 | <li class="mdc-deprecated-list-item" data-value="fruit">
|
272 | <span class="mdc-deprecated-list-item__ripple"></span>
|
273 | <span class="mdc-deprecated-list-item__text">Fruit</span>
|
274 | </li>
|
275 | </ul>
|
276 | </div>
|
277 | </div>
|
278 | ```
|
279 |
|
280 | #### Using the floating label as the placeholder
|
281 |
|
282 | Leave the `mdc-select__selected-text` element empty and don't specify an element as selected.
|
283 | If leaving the field empty should be a valid option, include an `mdc-deprecated-list-item` element at the beginning of
|
284 | the list with an empty `data-value` attribute.
|
285 |
|
286 | ```html
|
287 | <li class="mdc-deprecated-list-item mdc-deprecated-list-item--selected" aria-selected="true" role="option" data-value=""></li>
|
288 | ```
|
289 |
|
290 | #### Required select
|
291 |
|
292 | To style a select menu as required and enable validation, add the `mdc-select--required` class to the `mdc-select` element
|
293 | and set the `aria-required` attribute on the `mdc-select__anchor` element to be `"true"`.
|
294 |
|
295 | ```html
|
296 | <div class="mdc-select mdc-select--filled mdc-select--required">
|
297 | <div class="mdc-select__anchor" aria-required="true">
|
298 | <span class="mdc-select__ripple"></span>
|
299 | <span class="mdc-floating-label">Pick a Food Group</span>
|
300 | <span class="mdc-select__selected-text-container">
|
301 | <span class="mdc-select__selected-text"></span>
|
302 | </span>
|
303 | <span class="mdc-select__dropdown-icon">
|
304 | <svg
|
305 | class="mdc-select__dropdown-icon-graphic"
|
306 | viewBox="7 10 10 5" focusable="false">
|
307 | <polygon
|
308 | class="mdc-select__dropdown-icon-inactive"
|
309 | stroke="none"
|
310 | fill-rule="evenodd"
|
311 | points="7 10 12 15 17 10">
|
312 | </polygon>
|
313 | <polygon
|
314 | class="mdc-select__dropdown-icon-active"
|
315 | stroke="none"
|
316 | fill-rule="evenodd"
|
317 | points="7 15 12 10 17 15">
|
318 | </polygon>
|
319 | </svg>
|
320 | </span>
|
321 | <span class="mdc-line-ripple"></span>
|
322 | </div>
|
323 |
|
324 | <div class="mdc-select__menu mdc-menu mdc-menu-surface">
|
325 | ...
|
326 | </div>
|
327 | </div>
|
328 | ```
|
329 |
|
330 | > _NOTE_: To programmatically set a select as required, use the `required` property in the `MDCSelect` API.
|
331 |
|
332 | #### Disabled select
|
333 |
|
334 | Add the `mdc-select--disabled` class to the `mdc-select` element, set the
|
335 | `aria-disabled` attribute on the `mdc-select__selected-text` element to
|
336 | be `"true"`, and set the disabled attribute any hidden input element.
|
337 |
|
338 | ```html
|
339 | <div class="mdc-select mdc-select--filled mdc-select--disabled">
|
340 | <div class="mdc-select__anchor" aria-disabled="true">
|
341 | <span class="mdc-select__ripple"></span>
|
342 | <span class="mdc-floating-label">Pick a Food Group</span>
|
343 | <span class="mdc-select__selected-text-container">
|
344 | <span class="mdc-select__selected-text"></span>
|
345 | </span>
|
346 | <span class="mdc-select__dropdown-icon">
|
347 | <svg
|
348 | class="mdc-select__dropdown-icon-graphic"
|
349 | viewBox="7 10 10 5" focusable="false">
|
350 | <polygon
|
351 | class="mdc-select__dropdown-icon-inactive"
|
352 | stroke="none"
|
353 | fill-rule="evenodd"
|
354 | points="7 10 12 15 17 10">
|
355 | </polygon>
|
356 | <polygon
|
357 | class="mdc-select__dropdown-icon-active"
|
358 | stroke="none"
|
359 | fill-rule="evenodd"
|
360 | points="7 15 12 10 17 15">
|
361 | </polygon>
|
362 | </svg>
|
363 | </span>
|
364 | <span class="mdc-line-ripple"></span>
|
365 | </div>
|
366 |
|
367 | <div class="mdc-select__menu mdc-menu mdc-menu-surface">
|
368 | ...
|
369 | </div>
|
370 | </div>
|
371 | ```
|
372 |
|
373 | > _NOTE_: To programmatically set a select as disabled, use the `disabled` property in the `MDCSelect` API.
|
374 |
|
375 | #### Disabled options
|
376 |
|
377 | Add the `mdc-deprecated-list-item--disabled` class to list items that are disabled.
|
378 | Disabled list items are removed from the list items index and are ignored entirely. You cannot
|
379 | programmatically select a disabled list item.
|
380 |
|
381 | ```html
|
382 | <div class="mdc-select mdc-select--filled">
|
383 | <div class="mdc-select__anchor">
|
384 | ...
|
385 | </div>
|
386 |
|
387 | <div class="mdc-select__menu mdc-menu mdc-menu-surface">
|
388 | <ul class="mdc-deprecated-list">
|
389 | <li class="mdc-deprecated-list-item" data-value="">
|
390 | <span class="mdc-deprecated-list-item__ripple"></span>
|
391 | </li>
|
392 | <li class="mdc-deprecated-list-item" data-value="grains">
|
393 | <span class="mdc-deprecated-list-item__ripple"></span>
|
394 | <span class="mdc-deprecated-list-item__text">Bread, Cereal, Rice, and Pasta</span>
|
395 | </li>
|
396 | <li class="mdc-deprecated-list-item mdc-deprecated-list-item--selected mdc-deprecated-list-item--disabled" data-value="vegetables">
|
397 | <span class="mdc-deprecated-list-item__ripple"></span>
|
398 | <span class="mdc-deprecated-list-item__text">Vegetables</span>
|
399 | </li>
|
400 | <li class="mdc-deprecated-list-item" data-value="fruit">
|
401 | <span class="mdc-deprecated-list-item__ripple"></span>
|
402 | <span class="mdc-deprecated-list-item__text">Fruit</span>
|
403 | </li>
|
404 | </ul>
|
405 | </div>
|
406 | </div>
|
407 | ```
|
408 |
|
409 | ### Select with Helper Text
|
410 |
|
411 | The helper text provides supplemental information and/or validation messages to users. It appears when the select
|
412 | element is focused and disappears on blur by default, or it can be persistent.
|
413 | See [here](helper-text/) for more information on using helper text.
|
414 |
|
415 | ### Select with Leading Icons
|
416 |
|
417 | Leading icons can be added within the default or outlined variant of MDC Select as visual indicators as
|
418 | well as interaction targets. See [here](icon/) for more information on using icons.
|
419 |
|
420 | ### Select with No Label
|
421 |
|
422 | A label is not required if a separate, adjacent label is provided elsewhere. To correctly style
|
423 | MDC Select without a label, add the class `mdc-select--no-label` and remove the label from the
|
424 | structure.
|
425 |
|
426 | #### Filled
|
427 |
|
428 | ```html
|
429 | <div class="mdc-select mdc-select--filled mdc-select--no-label demo-width-class">
|
430 | <div class="mdc-select__anchor">
|
431 | <span class="mdc-select__ripple"></span>
|
432 | <span class="mdc-select__selected-text-container">
|
433 | <span class="mdc-select__selected-text"></span>
|
434 | </span>
|
435 | <span class="mdc-select__dropdown-icon">
|
436 | <svg
|
437 | class="mdc-select__dropdown-icon-graphic"
|
438 | viewBox="7 10 10 5" focusable="false">
|
439 | <polygon
|
440 | class="mdc-select__dropdown-icon-inactive"
|
441 | stroke="none"
|
442 | fill-rule="evenodd"
|
443 | points="7 10 12 15 17 10">
|
444 | </polygon>
|
445 | <polygon
|
446 | class="mdc-select__dropdown-icon-active"
|
447 | stroke="none"
|
448 | fill-rule="evenodd"
|
449 | points="7 15 12 10 17 15">
|
450 | </polygon>
|
451 | </svg>
|
452 | </span>
|
453 | <span class="mdc-line-ripple"></span>
|
454 | </div>
|
455 |
|
456 | <div class="mdc-select__menu mdc-menu mdc-menu-surface mdc-menu-surface--fullwidth">
|
457 | <ul class="mdc-deprecated-list">
|
458 | <li class="mdc-deprecated-list-item mdc-deprecated-list-item--selected" data-value="" aria-selected="true">
|
459 | <span class="mdc-deprecated-list-item__ripple"></span>
|
460 | </li>
|
461 | <li class="mdc-deprecated-list-item" data-value="grains">
|
462 | <span class="mdc-deprecated-list-item__ripple"></span>
|
463 | <span class="mdc-deprecated-list-item__text">Bread, Cereal, Rice, and Pasta</span>
|
464 | </li>
|
465 | <li class="mdc-deprecated-list-item" data-value="vegetables">
|
466 | <span class="mdc-deprecated-list-item__ripple"></span>
|
467 | <span class="mdc-deprecated-list-item__text">Vegetables</span>
|
468 | </li>
|
469 | <li class="mdc-deprecated-list-item" data-value="fruit">
|
470 | <span class="mdc-deprecated-list-item__ripple"></span>
|
471 | <span class="mdc-deprecated-list-item__text">Fruit</span>
|
472 | </li>
|
473 | </ul>
|
474 | </div>
|
475 | </div>
|
476 | ```
|
477 |
|
478 | #### Outlined
|
479 |
|
480 | ```html
|
481 | <div class="mdc-select mdc-select--outlined mdc-select--no-label demo-width-class">
|
482 | <div class="mdc-select__anchor">
|
483 | <span class="mdc-notched-outline">
|
484 | <span class="mdc-notched-outline__leading"></span>
|
485 | <span class="mdc-notched-outline__trailing"></span>
|
486 | </span>
|
487 | <span class="mdc-select__selected-text-container">
|
488 | <span class="mdc-select__selected-text"></span>
|
489 | </span>
|
490 | <span class="mdc-select__dropdown-icon">
|
491 | <svg
|
492 | class="mdc-select__dropdown-icon-graphic"
|
493 | viewBox="7 10 10 5" focusable="false">
|
494 | <polygon
|
495 | class="mdc-select__dropdown-icon-inactive"
|
496 | stroke="none"
|
497 | fill-rule="evenodd"
|
498 | points="7 10 12 15 17 10">
|
499 | </polygon>
|
500 | <polygon
|
501 | class="mdc-select__dropdown-icon-active"
|
502 | stroke="none"
|
503 | fill-rule="evenodd"
|
504 | points="7 15 12 10 17 15">
|
505 | </polygon>
|
506 | </svg>
|
507 | </span>
|
508 | </div>
|
509 |
|
510 | <!-- Other elements from the select remain. -->
|
511 | <div class="mdc-select__menu mdc-menu mdc-menu-surface mdc-menu-surface--fullwidth">...</div>
|
512 | </div>
|
513 | ```
|
514 |
|
515 | ## Style Customization
|
516 |
|
517 | #### CSS Classes
|
518 |
|
519 | | Class | Description |
|
520 | | --- | --- |
|
521 | | `mdc-select` | Mandatory. |
|
522 | | `mdc-select__anchor` | Mandatory. This element should be placed within the `mdc-select` element. |
|
523 | | `mdc-select__menu` | Mandatory. This class should be placed on the `mdc-menu` element within the `mdc-select` element. |
|
524 | | `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.
|
525 | | `mdc-select__selected-text-container` | Mandatory. This class wraps the `mdc-select__selected-text` and facilitates `text-overflow: ellipsis` on it. |
|
526 | | `mdc-select__selected-text` | Mandatory. This class should be placed on a `span` within the `mdc-select__anchor` element. |
|
527 | | `mdc-select__icon` | Optional. Should be placed on an `i` or `svg` element within the `mdc-select__anchor` element. Used for the leading icon.
|
528 | | `mdc-select--activated` | Optional. Styles the activated state of select. This class will be added automatically when menu is opened.
|
529 | | `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 `<select>` element. |
|
530 | | `mdc-select--outlined` | Optional. Styles the select as outlined select. |
|
531 | | `mdc-select--with-leading-icon` | Styles the select as a select with a leading icon. |
|
532 | | `mdc-select--no-label` | Styles the select as a select without a label. |
|
533 | > _NOTE_: To further customize the [MDCMenu](./../mdc-menu) or the [MDCList](./../mdc-list) component contained within the select, please refer to their respective documentation.
|
534 |
|
535 | ### Sass Mixins
|
536 |
|
537 | Mixins should be included in the context of a custom class applied to the component's root element, e.g. `.my-select`.
|
538 |
|
539 | Mixin | Description
|
540 | --- | ---
|
541 | `ink-color($state)` | Customizes the color of the selected item displayed in the select. Accepts a Map for `default` and `disabled` states.
|
542 | `container-fill-color($state)` | Customizes the background color of the select. Accepts a Map for `default` and `disabled` states.
|
543 | `dropdown-icon-color($state)` | Customizes the dropdown icon color of the select. Accepts a Map for `default`, `hover`, `focus`, and `disabled` states.
|
544 | `label-color($state)` | Customizes the label color of the select. Accepts a Map for `default`, `hover`, `focus`, and `disabled` states.
|
545 | `label-floating-color($state)` | Customizes the label color of the select when the label is floating. Accepts a Map for `default` and `hover` states.
|
546 | `bottom-line-color($state)` | Customizes the color of the bottom line of the select. Accepts a Map for `default`, `hover`, `focus`, and `disabled` states.
|
547 | `filled-shape-radius($radius, $density-scale, $rtl-reflexive)` | Sets rounded shape to filled select variant with given radius size. Set `$rtl-reflexive` to true to flip radius values in RTL context, defaults to false.
|
548 | `outline-color($state)` | Customizes the color of the notched outline. Accepts a Map for `default`, `hover`, `focus`, and `disabled` states.
|
549 | `outline-shape-radius($radius, $density-scale, $rtl-reflexive)` | Sets the border radius of the outlined select variant. Set `$rtl-reflexive` to true to flip radius values in RTL context, defaults to false.
|
550 | `filled-density($density-scale)` | Sets density scale for the filled select variant (Excluding filled select with leading icon).
|
551 | `filled-with-leading-icon-density($density-scale)` | Sets density scale for filled select with leading icon.
|
552 | `outlined-density($density-scale)` | Sets density scale for outlined select (Excluding outlined select with leading icon).
|
553 | `outlined-with-leading-icon-density($density-scale)` | Sets density scale for outlined select with leading icon.
|
554 | `filled-height($height)` | Sets height of the filled select variant (Excluding filled select with leading icon).
|
555 | `filled-with-leading-icon-height($height)` | Sets height of filled select with leading icon variant.
|
556 | `outlined-height($height)` | Sets height of outlined select variant (Excluding outlined select with leading icon).
|
557 | `outlined-with-leading-icon-height($height)` | Sets height of outlined select with leading icon variant.
|
558 | `variable-width($min-width)` | Sets the select behavior to change width dynamically based on content.
|
559 |
|
560 | > _NOTE_: To further customize the floating label, please see the [floating label documentation](./../mdc-floating-label/README.md).
|
561 |
|
562 | ## `MDCSelect` API
|
563 |
|
564 | The `MDCSelect` component API is modeled after a subset of the `HTMLSelectElement` functionality.
|
565 |
|
566 | Property | Type | Description
|
567 | --- | --- | ---
|
568 | `value` | `string` | The `value`/`data-value` of the currently selected option.
|
569 | `selectedIndex` | `number` | The index of the currently selected option. Set to -1 if no option is currently selected. Changing this property will update the select element.
|
570 | `disabled` | `boolean` | Whether or not the component is disabled. Setting this sets the disabled state on the component.
|
571 | `useDefaultValidation` | `boolean` | Whether or not to use the default validation scheme where a required select must be non-empty. Set to false for custom validation.
|
572 | `valid` | `boolean` | Whether or not the component is in a valid state. Setting this updates styles on the component, but does not affect the native validity state.
|
573 | `required` | `boolean` | Whether or not the component is required. Setting this updates the `required` or `aria-required` attribute on the component and enables validation.
|
574 | `leadingIconAriaLabel` | `string` (write-only) | Proxies to the foundation's `setLeadingIconAriaLabel` method.
|
575 | `leadingIconContent` | `string` (write-only) | Proxies to the foundation's `setLeadingIconContent` method.
|
576 | `helperTextContent` | `string` (write-only)| Proxies to the foundation's `setHelperTextContent` method when set.
|
577 | `ripple` | `MDCRipple` | Ripple instance attached to outlined select variant, or `null` for all other variants.
|
578 |
|
579 | Method Signature | Description
|
580 | --- | ---
|
581 | `layout() => void` | Re-calculates if the notched outline should be notched and if the label should float. Proxies to the foundation's `layout()` method.
|
582 | `layoutOptions() => void` | Synchronizes the list of options with the state of the foundation. Proxies to the foundation's `layoutOptions()` method. Call this whenever menu options are dynamically updated.
|
583 |
|
584 | ### Events
|
585 |
|
586 | Event Name | Data | Description
|
587 | --- | --- | ---
|
588 | `MDCSelect:change` | `{value: string, index: number}` | Used to indicate when an element has been selected. This event also includes the value of the item and the index.
|
589 |
|
590 | ## Usage within Web Frameworks
|
591 |
|
592 | If you are using a JavaScript framework, such as React or Angular, you can create a Select for your framework. Depending on your needs, you can use the _Simple Approach: Wrapping MDC Web Vanilla Components_, or the _Advanced Approach: Using Foundations and Adapters_. Please follow the instructions [here](../../docs/integrating-into-frameworks.md).
|
593 |
|
594 | ### `MDCSelectAdapter`
|
595 |
|
596 | | Method Signature | Description |
|
597 | | --- | --- |
|
598 | | `addClass(className: string) => void` | Adds a class to the select element. |
|
599 | | `removeClass(className: string) => void` | Removes a class from the select element. |
|
600 | | `hasClass(className: string) => boolean` | Returns true if the select element has the className in its classList. |
|
601 | | `activateBottomLine() => void` | Activates the bottom line component. |
|
602 | | `deactivateBottomLine() => void` | Deactivates the bottom line component. |
|
603 | | `hasLabel() => boolean` | Returns true if the select contains a label. |
|
604 | | `floatLabel(value: boolean) => void` | Floats or defloats label. |
|
605 | | `getLabelWidth() => number` | Returns the offsetWidth of the label element. |
|
606 | | `hasOutline() => boolean` | Returns true if the `select` has the notched outline element. |
|
607 | | `notchOutline(labelWidth: number) => void` | Switches the notched outline element to its "notched state." |
|
608 | | `closeOutline() => void` | Switches the notched outline element to its closed state. |
|
609 | | `setDisabled(isDisabled: boolean) => void` | Enables or disables the select. |
|
610 | | `openMenu() => void` | Opens the menu and applies activated styling. |
|
611 | | `setRippleCenter(normalizedX: number) => void` | Sets the line ripple center to the provided normalizedX value. |
|
612 | | `notifyChange(value: string) => void` | Emits the `MDCSelect:change` event when an element is selected. |
|
613 | | `setSelectedText(text: string) => void` | Sets the text content of the selectedText element to the given string. |
|
614 | | `isSelectAnchorFocused() => boolean` | Returns whether the select anchor element is focused. |
|
615 | | `getSelectAnchorAttr(attr: string) => string` | Gets the given attribute on the select anchor element. |
|
616 | | `setSelectAnchorAttr(attr: string, value: string) => void` | Sets the given attribute on the select anchor element. |
|
617 | | `removeSelectAnchorAttr(attr: string) => void` | Removes the given attribute on the select anchor element. |
|
618 | | `openMenu() => void` | Causes the menu element in the select to open. |
|
619 | | `closeMenu() => void` | Causes the menu element in the select to close. |
|
620 | | `getAnchorElement() => Element` | Returns the select anchor element. |
|
621 | | `setMenuAnchorElement(anchorEl: Element) => void` | Sets the menu anchor element. |
|
622 | | `setMenuAnchorCorner(anchorCorner: Corner) => void` | Sets the menu anchor corner. |
|
623 | | `setMenuWrapFocus(wrapFocus: boolean) => void` | Sets whether the menu should wrap focus. |
|
624 | | `focusMenuItemAtIndex(index: number) => void` | Focuses the menu item at the given index. |
|
625 | | `getMenuItemValues() => string[]` | Returns an array representing the VALUE_ATTR attributes of each menu item. |
|
626 | | `getMenuItemCount() => number` | Returns the number of menu items. |
|
627 | | `getMenuItemTextAtIndex(index: number) => string` | Gets the text content of the menu item element at the given index. |
|
628 | | `getSelectedIndex() => number` | Returns the selected index in the menu. |
|
629 | | `setSelectedIndex() => number` | Sets the selected index in the menu. |
|
630 | | `isTypeaheadInProgress() => boolean` | Returns whether typeahead is in progress in the menu. |
|
631 | | `typeaheadMatchItem: (nextChar: string, startingIndex: number) => number` | Adds a character to the list typeahead buffer and returns index of the next item in the list matching the buffer. |
|
632 | ### `MDCSelectFoundation`
|
633 |
|
634 | | Method Signature | Description |
|
635 | | --- | --- |
|
636 | | `notchOutline(openNotch: boolean) => void` | Opens/closes the notched outline. |
|
637 | | `getDisabled() => boolean` | Gets the disabled state. |
|
638 | | `setDisabled(isDisabled: boolean) => void` | Updates the disabled state. |
|
639 | | `handleFocus() => void` | Handles a focus event on the `select` element. |
|
640 | | `handleBlur() => void` | Handles a blur event on the `select` element. |
|
641 | | `handleClick(normalizedX: number) => void` | Sets the line ripple center to the normalizedX for the line ripple. |
|
642 | | `handleMenuOpened() => void` | Handles menu or menu surface opened event.
|
643 | | `handleMenuClosed() => void` | Handles menu or menu surface closed event.
|
644 | | `handleMenuItemAction() => void` | Handles menu selected event.
|
645 | | `handleChange() => void` | Handles a change to the `select` element's value. This must be called both for `change` events and programmatic changes requested via the component API. |
|
646 | | `handleKeydown(event: KeyboardEvent) => void` | Handles opening the menu when the `mdc-select__selected-text` element is focused and the user presses the `Enter` or `Space` key. |
|
647 | | `getSelectedIndex() => number` | Returns the index of the currently selected menu item. |
|
648 | | `setSelectedIndex(index: number) => void` | Handles setting the `mdc-select__selected-text` element and closing the menu. Also causes the label to float and outline to notch if needed. |
|
649 | | `getValue() => string` | Handles getting the value through the adapter. |
|
650 | | `setValue() => string` | Sets the selected index to the index of the menu item with the given value. |
|
651 | | `setUseDefaultValidation(useDefaultValidation: boolean) => void` | Enables or disables the default validation scheme where a required select must be non-empty. Set to false for custom validation.|
|
652 | | `setValid(isValid: boolean) => void` | Sets the valid state through the adapter. Note that default validation scheme where a required select is invalid if empty will still be honored subsequently unless `setUseDefaultValidation(false)` is also called.|
|
653 | | `isValid() => boolean` | Gets the valid state through the adapter's `checkValidity` API. |
|
654 | | `setRequired(isRequired: boolean) => void` | Sets the required state through the adapter. |
|
655 | | `getRequired() => boolean` | Gets the required state through the adapter. |
|
656 | | `init() => void` | Initializes the foundation. |
|
657 | | `layout() => void` | Re-calculates if the notched outline should be notched and if the label should float. |
|
658 | | `layoutOptions() => void` | Synchronizes the list of options with the state of the foundation. Call this whenever menu options are dynamically updated. |
|
659 | | `setLeadingIconAriaLabel(label: string) => void` | Sets the aria label of the leading icon. |
|
660 | | `setLeadingIconContent(content: string) => void` | Sets the text content of the leading icon. |
|
661 | | `setHelperTextContent(content: string) => void` | Sets the content of the helper text. |
|
662 |
|
663 | `MDCSelectFoundation` supports multiple optional sub-elements: helper text and icon. The foundations of these sub-elements must be passed in as constructor arguments to `MDCSelectFoundation`.
|