# Switch **This documentation is fully rendered on the [Material Web catalog](https://material-web.dev/components/switch/).** [Switches](https://m3.material.io/components/switch) toggle the state of an item on or off. * [Design article](https://m3.material.io/components/switch) * [API Documentation](#api) * [Source code](https://github.com/material-components/material-web/tree/main/switch) ## Usage Switches are similar to checkboxes, and can be unselected or selected. ```html ``` ### Icons Icons can be used to visually emphasize the switch's selected state. Switches can choose to display both icons or only selected icons. ```html ``` ### Label Associate a label with a switch using the `` element. ```html Wi-Fi Bluetooth ``` ## Accessibility Add an [`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) attribute to switches without labels or switches whose labels need to be more descriptive. ```html All ``` > Note: switches are not automatically labelled by `` elements and always > need an `aria-label`. See b/294081528. ## Theming Switches supports [Material theming](../theming/README.md) 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` | `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` * [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-switch.scss) ### Example ```html ``` ## API ### MdSwitch <md-switch> #### Properties 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` | #### Methods 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 #### Events Event | Description --- | --- `input` | Fired whenever `selected` changes due to user interaction (bubbles and composed). `change` | Fired whenever `selected` changes due to user interaction (bubbles).