mirror of
https://github.com/thejakubruzicka/MNotes.git
synced 2025-07-11 06:54:04 +02:00
221 lines
6.4 KiB
Markdown
221 lines
6.4 KiB
Markdown
|
<!-- 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.
|
||
|
freshness: { owner: 'lizmitchell' reviewed: '2025-05-20' }
|
||
|
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"
|
||
|
src="images/switch/hero.webp"
|
||
|
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} -->
|
||
|
* [API Documentation](#api)
|
||
|
* [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 -->
|
||
|
<!-- Need to add image -->
|
||
|
<!-- no-catalog-end -->
|
||
|
<!-- Need to add catalog-include "figures/<component>/usage.html" -->
|
||
|
|
||
|
```html
|
||
|
<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.
|
||
|
|
||
|
<!-- no-catalog-start -->
|
||
|
<!-- Need to add image -->
|
||
|
<!-- no-catalog-end -->
|
||
|
<!-- Need to add catalog-include "figures/<component>/usage.html" -->
|
||
|
|
||
|
```html
|
||
|
<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.
|
||
|
|
||
|
<!-- no-catalog-start -->
|
||
|
<!-- Need to add image -->
|
||
|
<!-- no-catalog-end -->
|
||
|
<!-- Need to add catalog-include "figures/<component>/usage.html" -->
|
||
|
|
||
|
```html
|
||
|
<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`](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
|
||
|
|
||
|
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` | `--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](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-switch.scss)
|
||
|
<!-- {.external} -->
|
||
|
|
||
|
### Example
|
||
|
|
||
|
<!-- no-catalog-start -->
|
||
|
<!-- Need to add image -->
|
||
|
<!-- no-catalog-end -->
|
||
|
<!-- Need to add catalog-include "figures/<component>/usage.html" -->
|
||
|
|
||
|
```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: 0px;
|
||
|
--md-switch-track-shape: 0px;
|
||
|
}
|
||
|
</style>
|
||
|
|
||
|
<md-switch></md-switch>
|
||
|
<md-switch selected></md-switch>
|
||
|
```
|
||
|
|
||
|
<!-- auto-generated API docs start -->
|
||
|
|
||
|
## API
|
||
|
|
||
|
|
||
|
### MdSwitch <code><md-switch></code>
|
||
|
|
||
|
#### Properties
|
||
|
|
||
|
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||
|
|
||
|
| 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` | |
|
||
|
|
||
|
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||
|
|
||
|
#### Methods
|
||
|
|
||
|
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||
|
|
||
|
| Method | Parameters | Returns | Description |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `formResetCallback` | _None_ | `void` | |
|
||
|
| `formStateRestoreCallback` | `state` | `void` | |
|
||
|
|
||
|
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||
|
|
||
|
#### Events
|
||
|
|
||
|
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||
|
|
||
|
| 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). |
|
||
|
|
||
|
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||
|
|
||
|
<!-- auto-generated API docs end -->
|