1 |
|
2 | title: "Switches"
|
3 | layout: detail
|
4 | section: components
|
5 | iconId: switch
|
6 | path: /catalog/input-controls/switches/
|
7 | -->
|
8 |
|
9 | # Selection controls: switches
|
10 |
|
11 | [Selection controls](https://material.io/components/selection-controls#usage)
|
12 | allow the user to select options.
|
13 |
|
14 | Switches toggle the state of a single setting on or off. They are the preferred
|
15 | way to adjust settings on mobile.
|
16 |
|
17 | ![Switch hero example for menu options](images/switch-hero.png)
|
18 |
|
19 | **Contents**
|
20 |
|
21 | * [Using switches](#using-switches)
|
22 | * [Switches](#switches)
|
23 | * [Other variants](#other-variants)
|
24 | * [API](#api)
|
25 | * [Usage within web frameworks](#usage-within-web-frameworks)
|
26 |
|
27 | ## Using switches
|
28 |
|
29 | Use switches to:
|
30 |
|
31 | * Toggle a single item on or off, on mobile and tablet
|
32 | * Immediately activate or deactivate something
|
33 |
|
34 | ### Installing switches
|
35 |
|
36 | ```
|
37 | npm install @material/switch
|
38 | ```
|
39 |
|
40 | ### Styles
|
41 |
|
42 | ```scss
|
43 | @use '@material/switch/styles';
|
44 | ```
|
45 |
|
46 | ### JavaScript instantiation
|
47 |
|
48 | The switch requires JavaScript to function, so it is necessary to instantiate
|
49 | `MDCSwitch` on the `mdc-switch` element.
|
50 |
|
51 | ```js
|
52 | import {MDCSwitch} from '@material/switch';
|
53 |
|
54 | for (const el of document.querySelectorAll('.mdc-switch')) {
|
55 | const switchControl = new MDCSwitch(el);
|
56 | }
|
57 | ```
|
58 |
|
59 | **Note: See [Importing the JS component](../../docs/importing-js.md) for more
|
60 | information on how to import JavaScript.**
|
61 |
|
62 | ## Switches
|
63 |
|
64 | ### Switch example
|
65 |
|
66 | ```html
|
67 | <button id="basic-switch" class="mdc-switch mdc-switch--unselected" type="button" role="switch" aria-checked="false">
|
68 | <div class="mdc-switch__track"></div>
|
69 | <div class="mdc-switch__handle-track">
|
70 | <div class="mdc-switch__handle">
|
71 | <div class="mdc-switch__shadow">
|
72 | <div class="mdc-elevation-overlay"></div>
|
73 | </div>
|
74 | <div class="mdc-switch__ripple"></div>
|
75 | <div class="mdc-switch__icons">
|
76 | <svg class="mdc-switch__icon mdc-switch__icon--on" viewBox="0 0 24 24">
|
77 | <path d="M19.69,5.23L8.96,15.96l-4.23-4.23L2.96,13.5l6,6L21.46,7L19.69,5.23z" />
|
78 | </svg>
|
79 | <svg class="mdc-switch__icon mdc-switch__icon--off" viewBox="0 0 24 24">
|
80 | <path d="M20 13H4v-2h16v2z" />
|
81 | </svg>
|
82 | </div>
|
83 | </div>
|
84 | </div>
|
85 | </button>
|
86 | <label for="basic-switch">off/on</label>
|
87 | ```
|
88 |
|
89 | ### Switch states
|
90 |
|
91 | Switches can be on or off. Switches have enabled, hover, focused, and pressed
|
92 | states.
|
93 |
|
94 | ![Switch states in a table. Columns are enabled, disabled, hover, focused,
|
95 | pressed. Rows are on or off.](images/switch-states.png)
|
96 |
|
97 | ## Other variants
|
98 |
|
99 | ### Initially disabled switch
|
100 |
|
101 | Add the `disabled` attribute to the `mdc-switch` element to disable the switch.
|
102 | This logic is handled by the `MDCSwitch.disabled` property, but you'll want to
|
103 | avoid a FOUC by initially adding this attribute.
|
104 |
|
105 | ```html
|
106 | <button id="disabled-switch" class="mdc-switch mdc-switch--unselected" type="button" role="switch" aria-checked="false" disabled>
|
107 | <div class="mdc-switch__track"></div>
|
108 | <div class="mdc-switch__handle-track">
|
109 | <div class="mdc-switch__handle">
|
110 | <div class="mdc-switch__shadow">
|
111 | <div class="mdc-elevation-overlay"></div>
|
112 | </div>
|
113 | <div class="mdc-switch__ripple"></div>
|
114 | <div class="mdc-switch__icons">
|
115 | <svg class="mdc-switch__icon mdc-switch__icon--on" viewBox="0 0 24 24">
|
116 | <path d="M19.69,5.23L8.96,15.96l-4.23-4.23L2.96,13.5l6,6L21.46,7L19.69,5.23z" />
|
117 | </svg>
|
118 | <svg class="mdc-switch__icon mdc-switch__icon--off" viewBox="0 0 24 24">
|
119 | <path d="M20 13H4v-2h16v2z" />
|
120 | </svg>
|
121 | </div>
|
122 | </div>
|
123 | </div>
|
124 | </button>
|
125 | <label for="disabled-switch">off/on</label>
|
126 | ```
|
127 |
|
128 | ### Initially "on" switch
|
129 |
|
130 | Add the `mdc-switch--selected` class and `aria-checked="true"` attribute to the
|
131 | `mdc-switch` element to toggle the switch to "on". This logic is handled by the
|
132 | `MDCSwitch.selected` method, but you'll want to avoid a FOUC by initially adding
|
133 | this class and attribute.
|
134 |
|
135 | ```html
|
136 | <button id="selected-switch" class="mdc-switch mdc-switch--selected" type="button" role="switch" aria-checked="true">
|
137 | <div class="mdc-switch__track"></div>
|
138 | <div class="mdc-switch__handle-track">
|
139 | <div class="mdc-switch__handle">
|
140 | <div class="mdc-switch__shadow">
|
141 | <div class="mdc-elevation-overlay"></div>
|
142 | </div>
|
143 | <div class="mdc-switch__ripple"></div>
|
144 | <div class="mdc-switch__icons">
|
145 | <svg class="mdc-switch__icon mdc-switch__icon--on" viewBox="0 0 24 24">
|
146 | <path d="M19.69,5.23L8.96,15.96l-4.23-4.23L2.96,13.5l6,6L21.46,7L19.69,5.23z" />
|
147 | </svg>
|
148 | <svg class="mdc-switch__icon mdc-switch__icon--off" viewBox="0 0 24 24">
|
149 | <path d="M20 13H4v-2h16v2z" />
|
150 | </svg>
|
151 | </div>
|
152 | </div>
|
153 | </div>
|
154 | </button>
|
155 | <label for="selected-switch">off/on</label>
|
156 | ```
|
157 |
|
158 | ## API
|
159 |
|
160 | ### CSS classes
|
161 |
|
162 | | CSS Class | Description |
|
163 | | -------------------------- | ---------------------------------------------- |
|
164 | | `mdc-switch` | Mandatory, for the parent element. |
|
165 | | `mdc-switch--unselected` | Optional, styles the switch as unselected ("off") |
|
166 | | `mdc-switch--selected` | Optional, styles the switch as selected ("on") |
|
167 | | `mdc-switch__track` | Mandatory, for the track element. |
|
168 | | `mdc-switch__handle-track` | Mandatory, for the handle's track element. |
|
169 | | `mdc-switch__handle` | Mandatory, for the handle element. |
|
170 | | `mdc-switch__shadow` | Mandatory, for the shadow effect. |
|
171 | | `mdc-elevation-overlay` | Mandatory, for the shadow effect's overlay in dark mode. |
|
172 | | `mdc-switch__ripple` | Mandatory, for the ripple effect. |
|
173 | | `mdc-switch__icons` | Mandatory, for the icons. |
|
174 | | `mdc-switch__icon` | Mandatory, for the icon elements. |
|
175 | | `mdc-switch__icon--on` | Mandatory, for the on icon. |
|
176 | | `mdc-switch__icon--off` | Mandatory, for the off icon. |
|
177 |
|
178 | ### Theme mixin
|
179 |
|
180 | The switch may be customized using the `theme()` mixin and providing an
|
181 | [MDC Theme](../mdc-theme) string (such as `primary`) or other values to the
|
182 | theme keys.
|
183 |
|
184 | ```scss
|
185 | @use '@material/switch';
|
186 | @use '@material/theme/color-palette';
|
187 | @use '@material/theme/shadow-dom';
|
188 |
|
189 | // Include for IE11 support
|
190 | // @include shadow-dom.enable-css-selector-fallback-declarations(true);
|
191 |
|
192 | .my-switch {
|
193 | @include switch.theme((
|
194 | selected-handle-color: color-palette.$teal-600,
|
195 | selected-track-color: color-palette.$teal-300,
|
196 | ));
|
197 | }
|
198 | ```
|
199 |
|
200 | View the [theme file](_switch-theme.scss) for available keys and built-in
|
201 | themes.
|
202 |
|
203 | ### `MDCSwitch` properties
|
204 |
|
205 | | Property | Value Type | Description |
|
206 | | ---------- | ---------- | -------------------------------------------------- |
|
207 | | `disabled` | Boolean | Indicates whether or not the switch is disabled. |
|
208 | | `selected` | Boolean | If true, the switch is on. If false, the switch is off. |
|
209 |
|
210 | ## Usage within web frameworks
|
211 |
|
212 | If you are using a JavaScript framework, such as React or Angular, you can
|
213 | create a switch for your framework. Depending on your needs, you can use the
|
214 | _Simple Approach: Wrapping MDC Web Vanilla Components_, or the _Advanced
|
215 | Approach: Using Foundations and Adapters_. Please follow the instructions
|
216 | [here](../../docs/integrating-into-frameworks.md).
|
217 |
|
218 | See [MDCSwitchAdapter](./adapter.ts) and [MDCSwitchFoundation](./foundation.ts)
|
219 | for up-to-date code documentation of switch's foundation API.
|