switch.md

Switch

This documentation is fully rendered on the Material Web catalog.

Switches toggle the state of an item on or off.

• Design article
• API Documentation
• Source code

Usage

Switches are similar to checkboxes, and can be unselected or selected.

<md-switch></md-switch>
<md-switch selected></md-switch>

Icons

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>

Label

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>

Accessibility

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 an aria-label. See b/294081528.

Theming

Switches supports Material theming and can be customized in terms of color and shape.

Tokens

Token	Default value
--md-switch-handle-color	--md-sys-color-outline
--md-switch-handle-shape	--md-sys-shape-corner-full
--md-switch-track-color	--md-sys-color-surface-container-highest
--md-switch-track-shape	--md-sys-shape-corner-full
--md-switch-selected-handle-color	--md-sys-color-on-primary
--md-switch-selected-track-color	--md-sys-color-primary

• All tokens

Example

<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>

API

MdSwitch <md-switch>

Properties

Property	Attribute	Type	Default	Description
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	name	string	undefined	The HTML name to use in form submission.
disabled	disabled	boolean	undefined	Whether or not the element is disabled.
form		HTMLFormElement	undefined	The associated form element with which this element's value will submit.
labels		NodeList	undefined	The labels this element is associated with.
validity		ValidityState	undefined	Returns a ValidityState object that represents the validity states of the element. https://developer.mozilla.org/en-US/docs/Web/API/ValidityState
validationMessage		string	undefined	Returns a validation error message or an empty string if the element is valid. https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/validationMessage
willValidate		boolean	undefined	Returns whether an element will successfully validate based on forms validation rules and constraints. Disabled and readonly elements will not validate. https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/willValidate

Methods

Method	Parameters	Returns	Description
formResetCallback	None	void
formStateRestoreCallback	state	void
checkValidity	None	boolean	Checks the element's constraint validation and returns true if the element is valid or false if not. If invalid, this method will dispatch an invalid event. https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/checkValidity
reportValidity	None	boolean	Checks the element's constraint validation and returns true if the element is valid or false if not. If invalid, this method will dispatch a cancelable invalid event. If not canceled, a the current validationMessage will be reported to the user. https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/reportValidity
setCustomValidity	error	void	Sets the element's constraint validation error message. When set to a non-empty string, validity.customError will be true and validationMessage will display the provided error. Use this method to customize error messages reported. https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity

Events

Event	Type	Bubbles	Composed	Description
input	InputEvent	No	No	Fired whenever selected changes due to user interaction (bubbles and composed).
change	Event	No	No	Fired whenever selected changes due to user interaction (bubbles).