A switch turns one setting on or off and applies the change at once. It is for a single binary choice, not for picking between options.
Every example on this page is the real component, not a picture. Click, tab and press Space to try it. Figma: Toggle Switch.
Choose a breakpoint, mode, size, state and value and the switch and its code update. Hover and focus are forced here. The switch is live: click it.
A switch turns one setting on or off and applies the change at once. It is for a single binary choice, not for picking between options.
Switch has three sizes (Large, Small, X-Small), a light and a dark mode, and four states, each off and on. It is a native <input type="checkbox" role="switch">, so the keyboard behavior comes from the browser.
This documentation has three pages. Examples & Guidelines (this page) shows when and how to use a switch. Specifications holds the values: tokens, sizes, measurements, states and requirements. Code shows how to add one to a page.
Use a switch for one setting that turns on or off, where the change takes effect at once. Use it to:
aria-label)A switch applies its change at once, so a list of settings needs no Save button. When the choice is saved on submit, use eco-checkbox.
To choose between options use eco-radio, and to switch between two related views or filters use eco-pill-segment-control.
The label names the setting. The switch shows the state, so a label that says “On” or “Off” says it twice and goes out of date when the switch moves.
| The user… | Use |
|---|---|
| turns one setting on or off, with immediate effect | Switch |
| picks any number of options, saved on submit | eco-checkbox |
| picks exactly one of several options | eco-radio |
| switches between two related views or filters | eco-pill-segment-control |
.form-switch-item--dark on dark surfaces.transform.body-md (Large) or body-sm, 8px from the track. The whole label is the click target.The focus ring is 2px with a 2px offset around the track.
Light and dark mode. Choose the mode to see every example on a light or a dark surface. Sizes are under Sizes below.
A switch applies its change at once, so a list of settings needs no Save button. The label names the setting; the switch shows the state, so never change the label to “On” or “Off”.
Only when the setting is named by its surroundings, for example a row in a table. It needs an aria-label.
Large and Small have the same 48×24px track and differ only in label size. X-Small (class .form-switch-item--xs) has a 32×16px track for dense layouts. The size does not change with the breakpoint; only the Large label does. Measurements are under Sizes in Specifications.
In a list, put the switches on one left edge with the labels after them, one setting per row. Use the same size for every switch in a list.
The track is grey when off and green when on, with a white thumb. Use the light version on light surfaces and the dark version (.form-switch-item--dark) on dark ones: surface-100 or surface-80. Token names and values are under Design Tokens in Specifications.
A click on the switch or the label toggles it, and the change applies at once. Space toggles the focused switch.
Hover changes the track color. The ring shows with :focus-visible only, for both off and on. All states are listed under States in Specifications.
A disabled switch is not focusable. It has a muted track, no thumb shadow and a text-disabled label.
The track color and the thumb move with a short transition. Reduced motion turns it off. Values are under Motion in Specifications.
All requirements are listed under Accessibility Requirements in Specifications.
Tab moves between switches. Space toggles the focused one. The focus ring shows with :focus-visible.
The control is a native input type="checkbox" role="switch" inside a label, so the name, the role and the on/off state are announced. Never build it from a div or a button. A switch without a visible label needs an aria-label.