blob: 0011f7d8b5605cb04d75c9cd8c07893517baa3b9 [file] [log] [blame]
Copybara botbe50d492023-11-30 00:16:42 +01001
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>&lt;input type=&quot;checkbox&quot;&gt;</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&#39;s content or function. Their design and use is therefore an important factor in the overall user experience. See the icon-toggle component&#39;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>&nbsp;1. Code a <code>&lt;label&gt;</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">&lt;label for=&quot;icon-toggle-1&quot;&gt;
11...
12&lt;/label&gt;
13</code></pre>
14<p>&nbsp;2. Inside the label, code an <code>&lt;input&gt;</code> element and give it a <code>type</code> attribute whose value is <code>&quot;checkbox&quot;</code>. Also give it an <code>id</code> attribute whose value matches the label&#39;s <code>for</code> attribute value.</p>
15<pre><code class="lang-html">&lt;label for=&quot;icon-toggle-1&quot;&gt;
16 &lt;input type=&quot;checkbox&quot; id=&quot;icon-toggle-1&quot;&gt;
17&lt;/label&gt;
18</code></pre>
19<p>&nbsp;3. Also inside the label, after the input element, code an <code>&lt;i&gt;</code> element containing the icon-toggle&#39;s desired icon.</p>
20<pre><code class="lang-html">&lt;label for=&quot;icon-toggle-1&quot;&gt;
21 &lt;input type=&quot;checkbox&quot; id=&quot;icon-toggle-1&quot;&gt;
22 &lt;i class=&quot;mdl-icon-toggle__label material-icons&quot;&gt;format_bold&lt;/i&gt;
23&lt;/label&gt;
24</code></pre>
25<p>&nbsp;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">&lt;label class=&quot;mdl-icon-toggle mdl-js-icon-toggle mdl-js-ripple-effect&quot; for=&quot;icon-toggle-1&quot;&gt;
27 &lt;input type=&quot;checkbox&quot; id=&quot;icon-toggle-1&quot; class=&quot;mdl-icon-toggle__input&quot;&gt;
28 &lt;i class=&quot;mdl-icon-toggle__label material-icons&quot;&gt;format_bold&lt;/i&gt;
29&lt;/label&gt;
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">&lt;label class=&quot;mdl-icon-toggle mdl-js-icon-toggle mdl-js-ripple-effect&quot; for=&quot;icon-toggle-1&quot;&gt;
35 &lt;input type=&quot;checkbox&quot; id=&quot;icon-toggle-1&quot; class=&quot;mdl-icon-toggle__input&quot;&gt;
36 &lt;i class=&quot;mdl-icon-toggle__label material-icons&quot;&gt;format_bold&lt;/i&gt;
37&lt;/label&gt;
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>&lt;input type=&quot;checkbox&quot; id=&quot;icon-toggle-5&quot; class=&quot;mdl-icon-toggle__input&quot; disabled&gt;</code>
79This attribute may be added or removed programmatically via scripting.</p>
80</blockquote>
81
82