Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(select): Update README to new format #2589

Merged
merged 4 commits into from
Apr 24, 2018
Merged

docs(select): Update README to new format #2589

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c79523a
docs(select): Update README to new format
Apr 18, 2018
2d5ef73
WIP Doc tweaks
Apr 23, 2018
124cd8f
Merge branch 'master' into feat/select/no-import-common
kfranqueiro Apr 24, 2018
8bf9b81
Merge branch 'master' into feat/select/no-import-common
kfranqueiro Apr 24, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 53 additions & 31 deletions packages/mdc-select/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,9 @@ browser's native `<select>` element. It is fully accessible, and fully RTL-aware
npm install @material/select
```

## Usage
## Basic Usage

### Using the full-fidelity JS component
### HTML Structure

```html
<div class="mdc-select">
Expand All @@ -58,7 +58,19 @@ npm install @material/select
</div>
```

Then with JS
### Styles

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

// Invoke mixins in the context of a custom class applied to the component's root element:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this necessary to get the default select? If not, it doesn't need to go under Basic Usage.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had done this as a replacement for the remark about including the mixins within a .foo-select custom class selector in the Sass mixins section, but I can put that back.

.my-select {
@include mdc-select-ink-color(blue);
...
}
```

### JavaScript Instantiation

```js
const select = new mdc.select.MDCSelect(document.querySelector('.mdc-select'));
Expand All @@ -69,12 +81,31 @@ select.listen('change', () => {

See [Importing the JS component](../../docs/importing-js.md) for more information on how to import JavaScript.

## Variants

### Select Box

The Select Box variant uses the same markup as the standard variant, with the addition of the `mdc-select--box`
modifier class on the root element.

```html
<div class="mdc-select mdc-select--box">
<select class="mdc-select__native-control">
...
</select>
<label class="mdc-floating-label">Pick a Food Group</label>
<div class="mdc-line-ripple"></div>
</div>
```

### Additional Information

#### Select with pre-selected option

When dealing with the select component that has pre-selected values, you'll want to ensure that you
render `mdc-floating-label` with the `mdc-floating-label--float-above` modifier class and the selected
option with the `selected` attribute. This will ensure that the label moves out
of the way of the select's value and prevents a Flash Of Unstyled Content (**FOUC**).
When dealing with a select component that has a pre-selected value, include the `mdc-floating-label--float-above`
modifier class on the `mdc-floating-label` element, and add the `selected` attribute to the selected option.
This will ensure that the label moves out of the way of the select's value and prevents a Flash Of Unstyled Content
(**FOUC**).

```html
<div class="mdc-select">
Expand All @@ -94,7 +125,7 @@ of the way of the select's value and prevents a Flash Of Unstyled Content (**FOU
</div>
```

#### Select with floating label as the placeholder
#### 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 `""`.
Expand All @@ -105,21 +136,13 @@ instead, add an initial `<option>` element with the `disabled` *and* `selected`

#### Disabled select

Add the `mdc-select--disabled` class to the `mdc-select` element and the `disabled` attribute to the
Add the `mdc-select--disabled` class to the `mdc-select` element, and add the `disabled` attribute to the
`<select>` element.

```html
<div class="mdc-select mdc-select--disabled">
<select class="mdc-select__native-control" disabled>
<option value="grains">
Bread, Cereal, Rice, and Pasta
</option>
<option value="vegetables">
Vegetables
</option>
<option value="fruit">
Fruit
</option>
...
</select>
<label class="mdc-floating-label">Pick a Food Group</label>
<div class="mdc-line-ripple"></div>
Expand Down Expand Up @@ -148,6 +171,8 @@ Since MDC Select uses native `<select>` and `<option>` elements, simply add the
</div>
```

## Style Customization

#### CSS Classes

| Class | Description |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think these were missing from before: mdc-select--disabled, mdc-select__native-control

Expand All @@ -157,9 +182,6 @@ Since MDC Select uses native `<select>` and `<option>` elements, simply add the

### Sass Mixins

To customize the colors of any part of the select, use the following mixins. We recommend you use
these mixins within CSS selectors like `.foo-select` to apply styling.

Mixin | Description
--- | ---
`mdc-select-ink-color($color)` | Customizes the color of the selected item displayed in the select.
Expand All @@ -170,25 +192,25 @@ Mixin | Description
`mdc-select-focused-bottom-line-color($color)` | Customizes the color of the bottom line of the select when focused.
`mdc-select-hover-bottom-line-color($color)` | Customizes the color of the bottom line when select is hovered.

> NOTE: To further customize label color please see the [floating label readme](./../mdc-floating-label/README.md).
> NOTE: To further customize the floating label, please see the [floating label documentation](./../mdc-floating-label/README.md).

### MDC Select Component API
## `MDCSelect` API

The MDC Select component API is modeled after a subset of the `HTMLSelectElement` functionality, and
is outlined below.
The `MDCSelect` component API is modeled after a subset of the `HTMLSelectElement` functionality.

#### Properties

| Property Name | Type | Description |
| Property | Type | Description |
| --- | --- | --- |
| `value` | `string` | The `value` of the currently selected option. |
| `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. |
| `disabled` | `boolean` | Whether or not the component is disabled. Settings this sets the disabled state on the component. |

#### Events
### Events

The MDC Select JS component emits a `change` event when the selected option changes as the result of a user action.

## Usage within Web Frameworks

The MDC Select JS component emits a `change` event when the selected option changes as
the result of a user action.
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](../integrating-into-frameworks.md).

### `MDCSelectAdapter`

Expand Down