1 | ## Introduction
|
2 |
|
3 | The Material Design Lite (MDL) **icon-toggle** component is an enhanced version of the standard HTML `<input type="checkbox">` element. An icon-toggle consists of a user defined icon that indicates, by visual highlighting, a binary condition that will be set or unset when the user clicks or touches it. Like checkboxes, icon-toggles may appear individually or in groups, and can be selected and deselected individually.
|
4 |
|
5 | Icon toggles, particularly as a replacement for certain checkboxes, can be a valuable feature in user interfaces, regardless of a site's content or function. Their design and use is therefore an important factor in the overall user experience. See the icon-toggle component's [Material Design specifications page](http://www.google.com/design/spec/components/buttons.html#buttons-other-buttons) for details.
|
6 |
|
7 | The icon-toggle component can have a more customized visual look than a standard checkbox, and may be initially or programmatically *disabled*.
|
8 |
|
9 | ### To include an MDL **icon-toggle** component:
|
10 |
|
11 | 1. Code a `<label>` element and give it a `for` attribute whose value is the unique id of the icon-toggle it will contain.
|
12 | ```html
|
13 | <label for="icon-toggle-1">
|
14 | ...
|
15 | </label>
|
16 | ```
|
17 | 2. Inside the label, code an `<input>` element and give it a `type` attribute whose value is `"checkbox"`. Also give it an `id` attribute whose value matches the label's `for` attribute value.
|
18 | ```html
|
19 | <label for="icon-toggle-1">
|
20 | <input type="checkbox" id="icon-toggle-1">
|
21 | </label>
|
22 | ```
|
23 | 3. Also inside the label, after the input element, code an `<i>` element containing the icon-toggle's desired icon.
|
24 | ```html
|
25 | <label for="icon-toggle-1">
|
26 | <input type="checkbox" id="icon-toggle-1">
|
27 | <i class="mdl-icon-toggle__label material-icons">format_bold</i>
|
28 | </label>
|
29 | ```
|
30 | 4. Add one or more MDL classes, separated by spaces, to the label and input elements, using the `class` attribute.
|
31 | ```html
|
32 | <label class="mdl-icon-toggle mdl-js-icon-toggle mdl-js-ripple-effect" for="icon-toggle-1">
|
33 | <input type="checkbox" id="icon-toggle-1" class="mdl-icon-toggle__input">
|
34 | <i class="mdl-icon-toggle__label material-icons">format_bold</i>
|
35 | </label>
|
36 | ```
|
37 |
|
38 | The icon-toggle component is ready for use.
|
39 |
|
40 | #### Example
|
41 |
|
42 | An icon-toggle with a ripple click effect.
|
43 |
|
44 | ```html
|
45 | <label class="mdl-icon-toggle mdl-js-icon-toggle mdl-js-ripple-effect" for="icon-toggle-1">
|
46 | <input type="checkbox" id="icon-toggle-1" class="mdl-icon-toggle__input">
|
47 | <i class="mdl-icon-toggle__label material-icons">format_bold</i>
|
48 | </label>
|
49 | ```
|
50 |
|
51 | ## Configuration options
|
52 |
|
53 | The MDL CSS classes apply various predefined visual and behavioral enhancements to the icon-toggle. The table below lists the available classes and their effects.
|
54 |
|
55 | | MDL class | Effect | Remarks |
|
56 | |-----------|--------|---------|
|
57 | | `mdl-icon-toggle` | Defines label as an MDL component | Required on label element|
|
58 | | `mdl-js-icon-toggle` | Assigns basic MDL behavior to label | Required on label element |
|
59 | | `mdl-icon-toggle__input` | Applies basic MDL behavior to icon-toggle | Required on input element (icon-toggle) |
|
60 | | `mdl-icon-toggle__label` | Applies basic MDL behavior to caption | Required on i element (icon) |
|
61 | | `mdl-js-ripple-effect` | Applies *ripple* click effect | Optional; goes on label element, not input element (icon-toggle) |
|
62 |
|
63 | >**Note:** Disabled versions of all available input types are provided, and are invoked with the standard HTML boolean attribute `disabled`. `<input type="checkbox" id="icon-toggle-5" class="mdl-icon-toggle__input" disabled>`
|
64 | >This attribute may be added or removed programmatically via scripting.
|