UNPKG

7.91 kBMarkdownView Raw
1<!--docs:
2title: "Switches"
3layout: detail
4section: components
5iconId: switch
6path: /catalog/input-controls/switches/
7-->
8
9# Selection controls: switches
10
11[Selection controls](https://material.io/components/selection-controls#usage)
12allow the user to select options.
13
14Switches toggle the state of a single setting on or off. They are the preferred
15way 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
29Use 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```
37npm install @material/switch
38```
39
40### Styles
41
42```scss
43@use '@material/switch/styles';
44```
45
46### JavaScript instantiation
47
48The switch requires JavaScript to function, so it is necessary to instantiate
49`MDCSwitch` on the `mdc-switch` element.
50
51```js
52import {MDCSwitch} from '@material/switch';
53
54for (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
60information 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
92The `mdc-switch__focus-ring` element ensures that a focus indicator is displayed
93in high contrast mode around the active/focused switch.
94
95### Switch states
96
97Switches can be on or off. Switches have enabled, hover, focused, and pressed
98states.
99
100![Switch states in a table. Columns are enabled, disabled, hover, focused,
101pressed. Rows are on or off.](images/switch-states.png)
102
103## Other variants
104
105### Initially disabled switch
106
107Add the `disabled` attribute to the `mdc-switch` element to disable the switch.
108This logic is handled by the `MDCSwitch.disabled` property, but you'll want to
109avoid 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
139Add 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
142this 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
192The 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
194theme 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
212View the [theme file](_switch-theme.scss) for available keys and built-in
213themes.
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
224If you are using a JavaScript framework, such as React or Angular, you can
225create a switch for your framework. Depending on your needs, you can use the
226_Simple Approach: Wrapping MDC Web Vanilla Components_, or the _Advanced
227Approach: Using Foundations and Adapters_. Please follow the instructions
228[here](../../docs/integrating-into-frameworks.md).
229
230See [MDCSwitchAdapter](./adapter.ts) and [MDCSwitchFoundation](./foundation.ts)
231for up-to-date code documentation of switch's foundation API.