2023-08-03 13:27:42 -07:00
<!-- catalog-only-start --><!-- ---
name: Switch
dirname: switch
-----><!-- catalog-only-end -->
<catalog-component-header>
<catalog-component-header-title slot="title">
# Switch
<!--*
# Document freshness: For more information, see go/fresh-source.
2024-03-28 08:55:41 -07:00
freshness: { owner: 'lizmitchell' reviewed: '2024-03-27' }
2023-08-03 13:27:42 -07:00
tag: 'docType:reference'
*-->
<!-- no-catalog-start -->
<!-- go/md-switch -->
<!-- [TOC] -->
<!-- external-only-start -->
**This documentation is fully rendered on the
[Material Web catalog ](https://material-web.dev/components/switch/ ).**
<!-- external-only-end -->
<!-- no-catalog-end -->
[Switches ](https://m3.material.io/components/switch )<!-- {.external} --> toggle the state
of an item on or off.
</catalog-component-header-title>
<img
class="hero"
2024-04-06 21:06:07 +02:00
src="images/switch/hero.webp"
2023-08-03 13:27:42 -07:00
alt="Two switches on a settings page for Wi-Fi and Bluetooth. The first is on and the second is off."
title="Switches on a settings page.">
</catalog-component-header>
* [Design article ](https://m3.material.io/components/switch ) <!-- {.external} -->
2023-09-25 11:19:49 -07:00
* [API Documentation ](#api )
2023-08-03 13:27:42 -07:00
* [Source code ](https://github.com/material-components/material-web/tree/main/switch )
<!-- {.external} -->
<!-- catalog-only-start -->
<!--
## Interactive Demo
{% playgroundexample dirname=dirname %}
-->
<!-- catalog-only-end -->
## Usage
Switches are similar to checkboxes, and can be unselected or selected.
<!-- no-catalog-start -->
2024-01-04 08:10:16 -08:00
<!-- Need to add image -->
2023-08-03 13:27:42 -07:00
<!-- no-catalog-end -->
2024-01-04 08:10:16 -08:00
<!-- Need to add catalog-include "figures/<component>/usage.html" -->
2023-08-03 13:27:42 -07:00
``` html
2023-08-10 10:20:54 -07:00
< md-switch > < / md-switch >
2023-08-03 13:27:42 -07:00
< 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.
<!-- no-catalog-start -->
2024-01-04 08:10:16 -08:00
<!-- Need to add image -->
2023-08-03 13:27:42 -07:00
<!-- no-catalog-end -->
2024-01-04 08:10:16 -08:00
<!-- Need to add catalog-include "figures/<component>/usage.html" -->
2023-08-03 13:27:42 -07:00
``` html
2023-08-10 10:20:54 -07:00
< md-switch icons > < / md-switch >
2023-08-03 13:27:42 -07:00
< md-switch icons selected > < / md-switch >
2023-08-10 10:20:54 -07:00
< md-switch icons show-only-selected-icon > < / md-switch >
2023-08-03 13:27:42 -07:00
< md-switch icons show-only-selected-icon selected > < / md-switch >
```
### Label
Associate a label with a switch using the `<label>` element.
<!-- no-catalog-start -->
2024-01-04 08:10:16 -08:00
<!-- Need to add image -->
2023-08-03 13:27:42 -07:00
<!-- no-catalog-end -->
2024-01-04 08:10:16 -08:00
<!-- Need to add catalog-include "figures/<component>/usage.html" -->
2023-08-03 13:27:42 -07:00
``` html
< label >
Wi-Fi
< md-switch selected > < / md-switch >
< / label >
< label for = "switch" > Bluetooth< / label >
2023-08-30 18:06:01 -07:00
< md-switch id = "switch" > < / md-switch >
2023-08-03 13:27:42 -07:00
```
## Accessibility
Add an
[`aria-label` ](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label )<!-- {.external} -->
attribute to switches without labels or switches whose labels need to be more
descriptive.
``` html
< 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
2023-09-11 09:32:19 -07:00
Switches supports [Material theming ](../theming/README.md ) and can be customized
in terms of color and shape.
2023-08-03 13:27:42 -07:00
### Tokens
Token | Default value
----------------------------------- | ------------------------------------------
`--md-switch-handle-color` | `--md-sys-color-outline`
2024-02-15 12:59:45 -08:00
`--md-switch-handle-shape` | `--md-sys-shape-corner-full`
2023-08-03 13:27:42 -07:00
`--md-switch-track-color` | `--md-sys-color-surface-container-highest`
2024-02-15 12:59:45 -08:00
`--md-switch-track-shape` | `--md-sys-shape-corner-full`
2023-08-03 13:27:42 -07:00
`--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 )
<!-- {.external} -->
### Example
<!-- no-catalog-start -->
2024-01-04 08:10:16 -08:00
<!-- Need to add image -->
2023-08-03 13:27:42 -07:00
<!-- no-catalog-end -->
2024-01-04 08:10:16 -08:00
<!-- Need to add catalog-include "figures/<component>/usage.html" -->
2023-08-03 13:27:42 -07:00
``` html
< 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 : 0 px ;
--md-switch-track-shape : 0 px ;
}
< / style >
< md-switch > < / md-switch >
< md-switch selected > < / md-switch >
```
2023-09-19 21:05:08 -07:00
<!-- auto-generated API docs start -->
## API
2023-09-25 21:32:35 +00:00
### MdSwitch <code><md-switch></code>
2023-09-19 21:05:08 -07:00
#### Properties
<!-- mdformat off(autogenerated might break rendering in catalog) -->
2024-06-04 21:57:37 -07:00
| 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.<br>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` . |
| `disabled` | | `boolean` | `undefined` | |
| `name` | | `string` | `undefined` | |
2023-09-19 21:05:08 -07:00
<!-- mdformat on(autogenerated might break rendering in catalog) -->
#### Methods
<!-- mdformat off(autogenerated might break rendering in catalog) -->
2024-06-04 21:57:37 -07:00
| Method | Parameters | Returns | Description |
| --- | --- | --- | --- |
| `formResetCallback` | _ None _ | `void` | |
| `formStateRestoreCallback` | `state` | `void` | |
2023-09-19 21:05:08 -07:00
<!-- mdformat on(autogenerated might break rendering in catalog) -->
#### Events
<!-- mdformat off(autogenerated might break rendering in catalog) -->
2024-06-04 21:57:37 -07:00
| Event | Type | [Bubbles ](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles ) | [Composed ](https://developer.mozilla.org/en-US/docs/Web/API/Event/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). |
2023-09-19 21:05:08 -07:00
<!-- mdformat on(autogenerated might break rendering in catalog) -->
<!-- auto-generated API docs end -->
