Skip to content
This repository has been archived by the owner on Jan 13, 2025. It is now read-only.

Commit

Permalink
docs(select): Reorganize / clean up enhanced select docs
Browse files Browse the repository at this point in the history
  • Loading branch information
Kenneth G. Franqueiro committed Oct 24, 2018
1 parent e3bd3d1 commit 5fb5d42
Showing 1 changed file with 103 additions and 79 deletions.
182 changes: 103 additions & 79 deletions packages/mdc-select/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ path: /catalog/input-controls/select-menus/
</a>
</div>-->

MDC Select provides Material Design single-option select menus. It functions as a wrapper around the
browser's native `<select>` element. It is fully accessible, and fully RTL-aware.
MDC Select provides Material Design single-option select menus. It supports using the browser's native `<select>`
element, or a MDC Menu. It is fully accessible, and fully RTL-aware.

## Design & API Documentation

Expand All @@ -37,6 +37,9 @@ npm install @material/select

## Basic Usage

This section documents how to use a MDC Select with a native `<select>` element. For information on using
MDC Select with a MDC Menu, see the [Variants](#variants) section below.

### HTML Structure

```html
Expand All @@ -59,10 +62,41 @@ npm install @material/select
</div>
```

The enhanced select uses an MDCMenu component to contain the list of options, but uses the `data-value` attribute
instead of `value`. The enhanced select requires that you set the `width` of the root element (containing the
`mdc-select`) element as well as setting the width of the `mdc-select__menu` element to match. This is best done
through the use of another class (ex. `demo-width-class`).
### Styles

For the native select, you can simply include the `mdc-select` Sass file.

```scss
@import "@material/select/mdc-select";
```

### JavaScript Instantiation

```js
const select = new mdc.select.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

### Enhanced Select

The enhanced 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 enhanced select requires that you set the `width` of the root element (containing the
`mdc-select` class) as well as setting the width of the `mdc-select__menu` element to match. This is best done
through the use of another class (e.g. `demo-width-class` in the example HTML and CSS below).

If you are using the enhanced select within an HTML form, you can include a hidden `<input>` element under the root
`mdc-select` element, and it will be synchronized when the value is updated via user interaction or programmatically.

```html
<div class="mdc-select demo-width-class">
Expand All @@ -72,13 +106,13 @@ through the use of another class (ex. `demo-width-class`).
<div class="mdc-select__menu mdc-menu mdc-menu-surface demo-width-class" role="listbox">
<ul class="mdc-list">
<li class="mdc-list-item mdc-list-item--selected" data-value="" aria-selected="true"></option>
<li class="mdc-list" data-value="grains">
<li class="mdc-list-item" data-value="grains">
Bread, Cereal, Rice, and Pasta
</li>
<li class="mdc-list" data-value="vegetables">
<li class="mdc-list-item" data-value="vegetables">
Vegetables
</li>
<li class="mdc-list" data-value="fruit">
<li class="mdc-list-item" data-value="fruit">
Fruit
</li>
</ul>
Expand All @@ -88,19 +122,7 @@ through the use of another class (ex. `demo-width-class`).
</div>
```

> NOTE: The `data-value` attribute is required for each list item in the enhanced select.
> NOTE: The `input type="hidden"` is optional, and will synchronize the value of the enhanced select for form submissions.
### Styles

For the native select version you can simply include the select Sass file.

```scss
@import "@material/select/mdc-select";
```

When using the enhanced select, you will also require the menu components.
When using the enhanced select, you will also need to load the Menu and List components' styles.

```scss
@import "@material/list/mdc-list";
Expand All @@ -111,21 +133,47 @@ When using the enhanced select, you will also require the menu components.
.demo-width-class {
width: 400px;
}

```

### JavaScript Instantiation
#### Usability Notes

```js
const select = new mdc.select.MDCSelect(document.querySelector('.mdc-select'));
select.listen('MDCSelect:change', () => {
alert(`Selected option at index ${select.selectedIndex} with value "${select.value}"`);
});
```
The enhanced select provides a look and feel more consistent with the rest of Material Design, but there are some
trade-offs to consider when choosing it over the native `<select>` element.

See [Importing the JS component](../../docs/importing-js.md) for more information on how to import JavaScript.
* **Keyboard type-ahead:** Native selects typically benefit from OS-implemented keyboard type-ahead support
(i.e. they will automatically select an item starting with the letters typed). This is not present in the enhanced select.
* **Mobile UI:** Mobile OSes implement native selects as a modal dialog or bottom sheet. The enhanced select always uses
an MDC Menu, which may not provide an optimal experience for small screens.

## Variants
#### Accessibility (a11y)

In order to have an accessible component for users, it's recommended that you follow the WAI-ARIA example for
[Collapsible Dropdown Listbox](https://www.w3.org/TR/wai-aria-practices/examples/listbox/listbox-collapsible.html).
The following is an example of the enhanced select component with all of the necessary aria attributes.

```html
<div class="mdc-select">
<input type="hidden" name="enhanced-select">
<i class="mdc-select__dropdown-icon"></i>
<div id="demo-selected-text" class="mdc-select__selected-text" role="button" aria-haspopup="listbox" aria-labelledby="demo-label demo-selected-text">Vegetables</div>
<div class="mdc-select__menu mdc-menu mdc-menu-surface" role="listbox">
<ul class="mdc-list">
<li class="mdc-list-item mdc-list-item--selected" data-value="" role="option"></li>
<li class="mdc-list-item" data-value="grains" role="option">
Bread, Cereal, Rice, and Pasta
</li>
<li class="mdc-list-item mdc-list-item--disabled" data-value="vegetables" aria-selected="true" aria-disabled="true" role="option">
Vegetables
</li>
<li class="mdc-list-item" data-value="fruit" role="option">
Fruit
</li>
</ul>
</div>
<label id="demo-label" class="mdc-floating-label mdc-floating-label--float-above">Pick a Food Group</label>
<div class="mdc-line-ripple"></div>
</div>
```

### Outlined Select

Expand Down Expand Up @@ -175,10 +223,7 @@ This will ensure that the label moves out of the way of the select's value and p
```

The enhanced select works in a similar way, but uses the `mdc-list-item--selected` class to set the selected item. The
enhanced select also needs the text from the selected element copied to the `mdc-select__selected-text` element. The
enhanced select requires that you set the `width` of the root element (containing the `mdc-select`) element as well as
setting the width of the `mdc-select__menu` element to match. This is best done through the use of another class
(ex. `demo-width-class`).
enhanced select also needs the text from the selected element copied to the `mdc-select__selected-text` element.

```html
<div class="mdc-select demo-width-class">
Expand All @@ -188,13 +233,13 @@ setting the width of the `mdc-select__menu` element to match. This is best done
<div class="mdc-select__menu demo-width-class mdc-menu mdc-menu-surface" role="listbox">
<ul class="mdc-list">
<li class="mdc-list-item" data-value=""></li>
<li class="mdc-list" data-value="grains">
<li class="mdc-list-item" data-value="grains">
Bread, Cereal, Rice, and Pasta
</li>
<li class="mdc-list mdc-list-item--selected" data-value="vegetables" aria-selected="true">
<li class="mdc-list-item mdc-list-item--selected" data-value="vegetables" aria-selected="true">
Vegetables
</li>
<li class="mdc-list" data-value="fruit">
<li class="mdc-list-item" data-value="fruit">
Fruit
</li>
</ul>
Expand All @@ -207,14 +252,20 @@ setting the width of the `mdc-select__menu` element to match. This is best done
#### Using the floating label as the placeholder

By default, `<select>` elements will select their first enabled option. In order to initially display a placeholder
instead, add an initial `<option>` element with the `disabled` *and* `selected` attributes set, and with `value` set to `""`.
instead, add an initial `<option>` element with the `selected` attribute set (and optionally `disabled`, if the field is
required), and with `value` set to `""`.

```html
<option value="" disabled selected></option>
```

For the enhanced select, simply leave the `mdc-select__selected-text` element empty and don't specify an element as
selected.
selected. If leaving the field empty should be a valid option, include an `mdc-list-item` element at the beginning of
the list with an empty `data-value` attribute.

```html
<li class="mdc-list-item mdc-list-item--selected" aria-selected="true" role="option" data-value=""></li>
```

#### Disabled select

Expand Down Expand Up @@ -282,13 +333,13 @@ programmatically select a disabled list item in the enhanced select.
<div class="mdc-select__menu mdc-menu mdc-menu-surface" role="listbox">
<ul class="mdc-list">
<li class="mdc-list-item" data-value=""></li>
<li class="mdc-list" data-value="grains">
<li class="mdc-list-item" data-value="grains">
Bread, Cereal, Rice, and Pasta
</li>
<li class="mdc-list mdc-list-item--selected mdc-list-item--disabled" data-value="vegetables" aria-selected="true" aria-disabled="true">
<li class="mdc-list-item mdc-list-item--selected mdc-list-item--disabled" data-value="vegetables" aria-selected="true" aria-disabled="true">
Vegetables
</li>
<li class="mdc-list" data-value="fruit">
<li class="mdc-list-item" data-value="fruit">
Fruit
</li>
</ul>
Expand All @@ -304,36 +355,6 @@ The helper text provides supplemental information and/or validation messages to
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.

#### Enhanced Select Accessibility (a11y)

In order to have an accessible component for users, it's recommended that you follow the WAI-ARIA example for
[Collapsible Dropdown Listbox](https://www.w3.org/TR/wai-aria-practices/examples/listbox/listbox-collapsible.html). An
example of the enhanced select component with all the necessary aria attributes is listed below.

```html
<div class="mdc-select">
<input type="hidden" name="enhanced-select">
<i class="mdc-select__dropdown-icon"></i>
<div id="demo-selected-text" class="mdc-select__selected-text" role="button" aria-haspopup="listbox" aria-labelledby="demo-label demo-selected-text">Vegetables</div>
<div class="mdc-select__menu mdc-menu mdc-menu-surface" role="listbox">
<ul class="mdc-list">
<li class="mdc-list-item" data-value="" role="option"></li>
<li class="mdc-list" data-value="grains" role="option">
Bread, Cereal, Rice, and Pasta
</li>
<li class="mdc-list mdc-list-item--selected mdc-list-item--disabled" data-value="vegetables" aria-selected="true" aria-disabled="true" role="option">
Vegetables
</li>
<li class="mdc-list" data-value="fruit" role="option">
Fruit
</li>
</ul>
</div>
<label id="demo-label" class="mdc-floating-label mdc-floating-label--float-above">Pick a Food Group</label>
<div class="mdc-line-ripple"></div>
</div>
```

### Select with Leading Icons

Leading icons can be added within the default or outlined variant of MDC Select as visual indicators as
Expand Down Expand Up @@ -392,6 +413,14 @@ The `MDCSelect` component API is modeled after a subset of the `HTMLSelectElemen
| `leadingIconAriaLabel` | string (write-only) | Proxies to the foundation's `setLeadingIconAriaLabel` method. |
| `leadingIconContent` | string (write-only) | Proxies to the foundation's `setLeadingIconContent` method. |
| `helperTextContent` | string (write-only)| Proxies to the foundation's `setHelperTextContent` method when set. |

### Events

Event Name | Data | Description
--- | --- | ---
`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.


### Events

The MDC Select JS component emits a `MDCSelect:change` event when the selected option changes as the result of a user action.
Expand Down Expand Up @@ -447,10 +476,5 @@ If you are using a JavaScript framework, such as React or Angular, you can creat
| `setLeadingIconAriaLabel(label: string) => void` | Sets the aria label of the leading icon. |
| `setLeadingIconContent(content: string) => void` | Sets the text content of the leading icon. |
| `setHelperTextContent(content: string) => void` | Sets the content of the helper text. |
### Events

Event Name | Data | Description
--- | --- | ---
`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.

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

0 comments on commit 5fb5d42

Please sign in to comment.