Copybara bot | be50d49 | 2023-11-30 00:16:42 +0100 | [diff] [blame] | 1 | |
| 2 | |
| 3 | |
| 4 | <h2 id="introduction">Introduction</h2> |
| 5 | <p>The Material Design Lite (MDL) <strong>icon-toggle</strong> component is an enhanced version of the standard HTML <code><input type="checkbox"></code> 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.</p> |
| 6 | <p>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 <a href="http://www.google.com/design/spec/components/buttons.html#buttons-other-buttons">Material Design specifications page</a> for details.</p> |
| 7 | <p>The icon-toggle component can have a more customized visual look than a standard checkbox, and may be initially or programmatically <em>disabled</em>.</p> |
| 8 | <h3 id="to-include-an-mdl-icon-toggle-component-">To include an MDL <strong>icon-toggle</strong> component:</h3> |
| 9 | <p> 1. Code a <code><label></code> element and give it a <code>for</code> attribute whose value is the unique id of the icon-toggle it will contain.</p> |
| 10 | <pre><code class="lang-html"><label for="icon-toggle-1"> |
| 11 | ... |
| 12 | </label> |
| 13 | </code></pre> |
| 14 | <p> 2. Inside the label, code an <code><input></code> element and give it a <code>type</code> attribute whose value is <code>"checkbox"</code>. Also give it an <code>id</code> attribute whose value matches the label's <code>for</code> attribute value.</p> |
| 15 | <pre><code class="lang-html"><label for="icon-toggle-1"> |
| 16 | <input type="checkbox" id="icon-toggle-1"> |
| 17 | </label> |
| 18 | </code></pre> |
| 19 | <p> 3. Also inside the label, after the input element, code an <code><i></code> element containing the icon-toggle's desired icon.</p> |
| 20 | <pre><code class="lang-html"><label for="icon-toggle-1"> |
| 21 | <input type="checkbox" id="icon-toggle-1"> |
| 22 | <i class="mdl-icon-toggle__label material-icons">format_bold</i> |
| 23 | </label> |
| 24 | </code></pre> |
| 25 | <p> 4. Add one or more MDL classes, separated by spaces, to the label and input elements, using the <code>class</code> attribute.</p> |
| 26 | <pre><code class="lang-html"><label class="mdl-icon-toggle mdl-js-icon-toggle mdl-js-ripple-effect" for="icon-toggle-1"> |
| 27 | <input type="checkbox" id="icon-toggle-1" class="mdl-icon-toggle__input"> |
| 28 | <i class="mdl-icon-toggle__label material-icons">format_bold</i> |
| 29 | </label> |
| 30 | </code></pre> |
| 31 | <p>The icon-toggle component is ready for use.</p> |
| 32 | <h4 id="example">Example</h4> |
| 33 | <p>An icon-toggle with a ripple click effect.</p> |
| 34 | <pre><code class="lang-html"><label class="mdl-icon-toggle mdl-js-icon-toggle mdl-js-ripple-effect" for="icon-toggle-1"> |
| 35 | <input type="checkbox" id="icon-toggle-1" class="mdl-icon-toggle__input"> |
| 36 | <i class="mdl-icon-toggle__label material-icons">format_bold</i> |
| 37 | </label> |
| 38 | </code></pre> |
| 39 | <h2 id="configuration-options">Configuration options</h2> |
| 40 | <p>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.</p> |
| 41 | <table> |
| 42 | <thead> |
| 43 | <tr> |
| 44 | <th>MDL class</th> |
| 45 | <th>Effect</th> |
| 46 | <th>Remarks</th> |
| 47 | </tr> |
| 48 | </thead> |
| 49 | <tbody> |
| 50 | <tr> |
| 51 | <td><code>mdl-icon-toggle</code></td> |
| 52 | <td>Defines label as an MDL component</td> |
| 53 | <td>Required on label element</td> |
| 54 | </tr> |
| 55 | <tr> |
| 56 | <td><code>mdl-js-icon-toggle</code></td> |
| 57 | <td>Assigns basic MDL behavior to label</td> |
| 58 | <td>Required on label element</td> |
| 59 | </tr> |
| 60 | <tr> |
| 61 | <td><code>mdl-icon-toggle__input</code></td> |
| 62 | <td>Applies basic MDL behavior to icon-toggle</td> |
| 63 | <td>Required on input element (icon-toggle)</td> |
| 64 | </tr> |
| 65 | <tr> |
| 66 | <td><code>mdl-icon-toggle__label</code></td> |
| 67 | <td>Applies basic MDL behavior to caption</td> |
| 68 | <td>Required on i element (icon)</td> |
| 69 | </tr> |
| 70 | <tr> |
| 71 | <td><code>mdl-js-ripple-effect</code></td> |
| 72 | <td>Applies <em>ripple</em> click effect</td> |
| 73 | <td>Optional; goes on label element, not input element (icon-toggle)</td> |
| 74 | </tr> |
| 75 | </tbody> |
| 76 | </table> |
| 77 | <blockquote> |
| 78 | <p><strong>Note:</strong> Disabled versions of all available input types are provided, and are invoked with the standard HTML boolean attribute <code>disabled</code>. <code><input type="checkbox" id="icon-toggle-5" class="mdl-icon-toggle__input" disabled></code> |
| 79 | This attribute may be added or removed programmatically via scripting.</p> |
| 80 | </blockquote> |
| 81 | |
| 82 | |