This documentation is fully rendered on the Material Web catalog.
Switches toggle the state of an item on or off.
Switches are similar to checkboxes, and can be unselected or selected.
<md-switch></md-switch>
<md-switch selected></md-switch>
Icons can be used to visually emphasize the switch's selected state. Switches can choose to display both icons or only selected icons.
<md-switch icons></md-switch>
<md-switch icons selected></md-switch>
<md-switch icons show-only-selected-icon></md-switch>
<md-switch icons show-only-selected-icon selected></md-switch>
Associate a label with a switch using the <label>
element.
<label>
Wi-Fi
<md-switch selected></md-switch>
</label>
<label for="switch">Bluetooth</label>
<md-switch id="switch"></md-switch>
Add an
aria-label
attribute to switches without labels or switches whose labels need to be more
descriptive.
<md-switch aria-label="Lights"></md-switch>
<label>
All
<md-switch aria-label="All notifications"></md-switch>
</label>
Note: switches are not automatically labelled by
<label>
elements and always need anaria-label
. See b/294081528.
Switches supports Material theming and can be customized in terms of color and shape.
Token | Default value |
---|---|
--md-switch-handle-color |
--md-sys-color-outline |
--md-switch-handle-shape |
9999px |
--md-switch-track-color |
--md-sys-color-surface-container-highest |
--md-switch-track-shape |
9999px |
--md-switch-selected-handle-color |
--md-sys-color-on-primary |
--md-switch-selected-track-color |
--md-sys-color-primary |
<style>
:root {
/* System tokens */
--md-sys-color-primary: #006a6a;
--md-sys-color-on-primary: #ffffff;
--md-sys-color-outline: #6f7979;
--md-sys-color-surface-container-highest: #dde4e3;
/* Component tokens */
--md-switch-handle-shape: 0px;
--md-switch-track-shape: 0px;
}
</style>
<md-switch></md-switch>
<md-switch selected></md-switch>
Property | Attribute | Type | Default | Description |
---|---|---|---|---|
disabled |
disabled |
boolean |
false |
Disables the switch and makes it non-interactive. |
selected |
selected |
boolean |
false |
Puts the switch in the selected state and sets the form submission value to the value property. |
icons |
icons |
boolean |
false |
Shows both the selected and deselected icons. |
showOnlySelectedIcon |
show-only-selected-icon |
boolean |
false |
Shows only the selected icon, and not the deselected icon. If true , overrides the behavior of the icons property. |
required |
required |
boolean |
false |
When true, require the switch to be selected when participating in form submission. https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#validation |
value |
value |
string |
'on' |
The value associated with this switch on form submission. null is submitted when selected is false . |
name |
string |
undefined |
||
form |
HTMLFormElement |
undefined |
||
labels |
NodeList |
undefined |
||
validity |
ValidityState |
undefined |
||
validationMessage |
string |
undefined |
||
willValidate |
boolean |
undefined |
Method | Parameters | Returns | Description |
---|---|---|---|
checkValidity |
None | boolean |
Checks the switch's native validation and returns whether or not the element is valid. If invalid, this method will dispatch the invalid event.https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/checkValidity |
reportValidity |
None | boolean |
Checks the switch's native validation and returns whether or not the element is valid. If invalid, this method will dispatch the invalid event.The validationMessage is reported to the user by the browser. Use setCustomValidity() to customize the validationMessage .https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/reportValidity |
setCustomValidity |
error |
void |
Sets the switch's native validation error message. This is used to customize validationMessage .When the error is not an empty string, the switch is considered invalid and validity.customError will be true.https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity |
Event | Description |
---|---|
input |
Fired whenever selected changes due to user interaction (bubbles and composed). |
change |
Fired whenever selected changes due to user interaction (bubbles). |