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 | 
|
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 | <span class="mdc-switch__focus-ring-wrapper">
|
86 | <div class="mdc-switch__focus-ring"></div>
|
87 | </span>
|
88 | </button>
|
89 | <label for="basic-switch">off/on</label>
|
90 | ```
|
91 |
|
92 | The `mdc-switch__focus-ring` element ensures that a focus indicator is displayed
|
93 | in high contrast mode around the active/focused switch.
|
94 |
|
95 | ### Switch states
|
96 |
|
97 | Switches can be on or off. Switches have enabled, hover, focused, and pressed
|
98 | states.
|
99 |
|
100 | 
|
102 |
|
103 | ## Other variants
|
104 |
|
105 | ### Initially disabled switch
|
106 |
|
107 | Add the `disabled` attribute to the `mdc-switch` element to disable the switch.
|
108 | This logic is handled by the `MDCSwitch.disabled` property, but you'll want to
|
109 | avoid a FOUC by initially adding this attribute.
|
110 |
|
111 | ```html
|
112 | <button id="disabled-switch" class="mdc-switch mdc-switch--unselected" type="button" role="switch" aria-checked="false" disabled>
|
113 | <div class="mdc-switch__track"></div>
|
114 | <div class="mdc-switch__handle-track">
|
115 | <div class="mdc-switch__handle">
|
116 | <div class="mdc-switch__shadow">
|
117 | <div class="mdc-elevation-overlay"></div>
|
118 | </div>
|
119 | <div class="mdc-switch__ripple"></div>
|
120 | <div class="mdc-switch__icons">
|
121 | <svg class="mdc-switch__icon mdc-switch__icon--on" viewBox="0 0 24 24">
|
122 | <path d="M19.69,5.23L8.96,15.96l-4.23-4.23L2.96,13.5l6,6L21.46,7L19.69,5.23z" />
|
123 | </svg>
|
124 | <svg class="mdc-switch__icon mdc-switch__icon--off" viewBox="0 0 24 24">
|
125 | <path d="M20 13H4v-2h16v2z" />
|
126 | </svg>
|
127 | </div>
|
128 | </div>
|
129 | </div>
|
130 | <span class="mdc-switch__focus-ring-wrapper">
|
131 | <div class="mdc-switch__focus-ring"></div>
|
132 | </span>
|
133 | </button>
|
134 | <label for="disabled-switch">off/on</label>
|
135 | ```
|
136 |
|
137 | ### Initially "on" switch
|
138 |
|
139 | Add the `mdc-switch--selected` class and `aria-checked="true"` attribute to the
|
140 | `mdc-switch` element to toggle the switch to "on". This logic is handled by the
|
141 | `MDCSwitch.selected` method, but you'll want to avoid a FOUC by initially adding
|
142 | this class and attribute.
|
143 |
|
144 | ```html
|
145 | <button id="selected-switch" class="mdc-switch mdc-switch--selected" type="button" role="switch" aria-checked="true">
|
146 | <div class="mdc-switch__track"></div>
|
147 | <div class="mdc-switch__handle-track">
|
148 | <div class="mdc-switch__handle">
|
149 | <div class="mdc-switch__shadow">
|
150 | <div class="mdc-elevation-overlay"></div>
|
151 | </div>
|
152 | <div class="mdc-switch__ripple"></div>
|
153 | <div class="mdc-switch__icons">
|
154 | <svg class="mdc-switch__icon mdc-switch__icon--on" viewBox="0 0 24 24">
|
155 | <path d="M19.69,5.23L8.96,15.96l-4.23-4.23L2.96,13.5l6,6L21.46,7L19.69,5.23z" />
|
156 | </svg>
|
157 | <svg class="mdc-switch__icon mdc-switch__icon--off" viewBox="0 0 24 24">
|
158 | <path d="M20 13H4v-2h16v2z" />
|
159 | </svg>
|
160 | </div>
|
161 | </div>
|
162 | </div>
|
163 | <span class="mdc-switch__focus-ring-wrapper">
|
164 | <div class="mdc-switch__focus-ring"></div>
|
165 | </span>
|
166 | </button>
|
167 | <label for="selected-switch">off/on</label>
|
168 | ```
|
169 |
|
170 | ## API
|
171 |
|
172 | ### CSS classes
|
173 |
|
174 | | CSS Class | Description |
|
175 | | -------------------------- | ---------------------------------------------- |
|
176 | | `mdc-switch` | Mandatory, for the parent element. |
|
177 | | `mdc-switch--unselected` | Optional, styles the switch as unselected ("off") |
|
178 | | `mdc-switch--selected` | Optional, styles the switch as selected ("on") |
|
179 | | `mdc-switch__track` | Mandatory, for the track element. |
|
180 | | `mdc-switch__handle-track` | Mandatory, for the handle's track element. |
|
181 | | `mdc-switch__handle` | Mandatory, for the handle element. |
|
182 | | `mdc-switch__shadow` | Mandatory, for the shadow effect. |
|
183 | | `mdc-elevation-overlay` | Mandatory, for the shadow effect's overlay in dark mode. |
|
184 | | `mdc-switch__ripple` | Mandatory, for the ripple effect. |
|
185 | | `mdc-switch__icons` | Mandatory, for the icons. |
|
186 | | `mdc-switch__icon` | Mandatory, for the icon elements. |
|
187 | | `mdc-switch__icon--on` | Mandatory, for the on icon. |
|
188 | | `mdc-switch__icon--off` | Mandatory, for the off icon. |
|
189 |
|
190 | ### Theme mixin
|
191 |
|
192 | The switch may be customized using the `theme()` mixin and providing an
|
193 | [MDC Theme](../mdc-theme) string (such as `primary`) or other values to the
|
194 | theme keys.
|
195 |
|
196 | ```scss
|
197 | @use '@material/switch';
|
198 | @use '@material/theme/color-palette';
|
199 | @use '@material/theme/shadow-dom';
|
200 |
|
201 | // Include for IE11 support
|
202 | // @include shadow-dom.enable-css-selector-fallback-declarations(true);
|
203 |
|
204 | .my-switch {
|
205 | @include switch.theme((
|
206 | selected-handle-color: color-palette.$teal-600,
|
207 | selected-track-color: color-palette.$teal-300,
|
208 | ));
|
209 | }
|
210 | ```
|
211 |
|
212 | View the [theme file](_switch-theme.scss) for available keys and built-in
|
213 | themes.
|
214 |
|
215 | ### `MDCSwitch` properties
|
216 |
|
217 | | Property | Value Type | Description |
|
218 | | ---------- | ---------- | -------------------------------------------------- |
|
219 | | `disabled` | Boolean | Indicates whether or not the switch is disabled. |
|
220 | | `selected` | Boolean | If true, the switch is on. If false, the switch is off. |
|
221 |
|
222 | ## Usage within web frameworks
|
223 |
|
224 | If you are using a JavaScript framework, such as React or Angular, you can
|
225 | create a switch for your framework. Depending on your needs, you can use the
|
226 | _Simple Approach: Wrapping MDC Web Vanilla Components_, or the _Advanced
|
227 | Approach: Using Foundations and Adapters_. Please follow the instructions
|
228 | [here](../../docs/integrating-into-frameworks.md).
|
229 |
|
230 | See [MDCSwitchAdapter](./adapter.ts) and [MDCSwitchFoundation](./foundation.ts)
|
231 | for up-to-date code documentation of switch's foundation API.
|