| 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>switch</strong> component is an enhanced version of the standard HTML <code><input type="checkbox"></code> element. A switch consists of a short horizontal "track" with a prominent circular state indicator and, typically, text that clearly communicates a binary condition that will be set or unset when the user clicks or touches it. Like checkboxes, switches may appear individually or in groups, and can be selected and deselected individually. However, switches provide a more intuitive visual representation of their state: left/gray for <em>off</em>, right/colored for <em>on</em>. The MDL switch component allows you to add both display and click effects.</p> |
| 6 | <p>Switches, 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 switch component's <a href="http://www.google.com/design/spec/components/selection-controls.html#selection-controls-switch">Material Design specifications page</a> for details.</p> |
| 7 | <p>The enhanced switch component has a more vivid visual look than a standard checkbox, and may be initially or programmatically <em>disabled</em>.</p> |
| 8 | <h3 id="to-include-an-mdl-switch-component-">To include an MDL <strong>switch</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 switch it will contain.</p> |
| 10 | <pre><code class="lang-html"><label for="switch1"> |
| 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="switch1"> |
| 16 | <input type="checkbox" id="switch1"> |
| 17 | </label> |
| 18 | </code></pre> |
| 19 | <p> 3. Also inside the label, after the checkbox, code a <code><span></code> element containing the switch's text caption.</p> |
| 20 | <pre><code class="lang-html"><label for="switch1"> |
| 21 | <input type="checkbox" id="switch1"> |
| 22 | <span>Sound off/on</span> |
| 23 | </label> |
| 24 | </code></pre> |
| 25 | <p> 4. Add one or more MDL classes, separated by spaces, to the label, switch, and caption using the <code>class</code> attribute.</p> |
| 26 | <pre><code class="lang-html"><label for="switch1" class="mdl-switch mdl-js-switch"> |
| 27 | <input type="checkbox" id="switch1" class="mdl-switch__input"> |
| 28 | <span class="mdl-switch__label">Sound off/on</span> |
| 29 | </label> |
| 30 | </code></pre> |
| 31 | <p>The switch component is ready for use.</p> |
| 32 | <h4 id="example">Example</h4> |
| 33 | <p>A switch with a ripple click effect.</p> |
| 34 | <pre><code class="lang-html"><label for="switch1" class="mdl-switch mdl-js-switch mdl-js-ripple-effect"> |
| 35 | <input type="checkbox" id="switch1" class="mdl-switch__input"> |
| 36 | <span class="mdl-switch__label">Sound off/on</span> |
| 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 switch. 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-switch</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-switch</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-switch__input</code></td> |
| 62 | <td>Applies basic MDL behavior to switch</td> |
| 63 | <td>Required on input element (switch)</td> |
| 64 | </tr> |
| 65 | <tr> |
| 66 | <td><code>mdl-switch__label</code></td> |
| 67 | <td>Applies basic MDL behavior to caption</td> |
| 68 | <td>Required on span element (caption)</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 (switch)</td> |
| 74 | </tr> |
| 75 | </tbody> |
| 76 | </table> |
| 77 | <blockquote> |
| 78 | <p><strong>Note:</strong> Disabled versions of all available switch types are provided, and are invoked with the standard HTML boolean attribute <code>disabled</code>. <code><input type="checkbox" id="switch5" class="mdl-switch__input" disabled></code> |
| 79 | This attribute may be added or removed programmatically via scripting.</p> |
| 80 | </blockquote> |
| 81 | |
| 82 | |