Skip to main content brightness_auto motion_photos_off palette download more_vert
toc

Switch

Switches toggle the state of an item on or off.

View as Markdown

<label>
  Wi-Fi
  <md-gb-switch selected></md-gb-switch>
</label>

Install with shadcn/ui: npx shadcn@latest add https://material-web.dev/3.0/r/md-switch.json (setup)

Usage guidelines

Link to “Usage guidelines”
  • Use for settings. Switches are the best way to let people adjust a setting. Use a switch, not a radio button, when each item in a list is controlled on its own.
  • Visible at a glance. Make the on or off state clear, and let the change take effect right away.
  • Label with text. Put the label next to the switch in a <label>. Its text color stays the same, even when the switch changes.

Anatomy

Link to “Anatomy”

A switch has a track, a handle and optional icons shown in the handle.

close check 
<md-gb-switch aria-label="Airplane mode" selected>
  <md-gb-icon slot="off-icon">close</md-gb-icon>
  <md-gb-icon slot="on-icon">check</md-gb-icon>
</md-gb-switch>

Examples

Link to “Examples”

Selected

Link to “Selected”

Add selected to start with the switch on.

<label>
  Wi-Fi
  <md-gb-switch selected></md-gb-switch>
</label>
<label for="bluetooth">Bluetooth</label>
<md-gb-switch id="bluetooth"></md-gb-switch>

Icons

Link to “Icons”

Icons in the on-icon and off-icon slots appear in the handle. Fill only on-icon to show an icon just when the switch is on.

check close 
<md-gb-switch aria-label="Notifications">
  <md-gb-icon slot="on-icon">check</md-gb-icon>
  <md-gb-icon slot="off-icon">close</md-gb-icon>
</md-gb-switch>
check 
<md-gb-switch aria-label="Dark mode" selected>
  <md-gb-icon slot="on-icon">check</md-gb-icon>
</md-gb-switch>

Disabled

Link to “Disabled”

A disabled switch can't be changed.

<md-gb-switch aria-label="Sync off" disabled></md-gb-switch>
<md-gb-switch aria-label="Sync on" disabled selected></md-gb-switch>

In a form

Link to “In a form”

A switch submits its value (on by default) under its name when it is selected, and required means it must be on.

Continue 
<form>
  <label>
    Accept terms
    <md-gb-switch name="terms" required></md-gb-switch>
  </label>
  <md-gb-button type="submit">Continue</md-gb-button>
</form>

Accessibility

Link to “Accessibility”
  • A switch has the switch role. It takes its name from an adjacent <label>, or from an explicit aria-label, which wins over the label.
  • Add an aria-label to a switch with no visible label.
  • Space toggles the switch.
<md-gb-switch aria-label="Lights"></md-gb-switch>

Compatibility

Link to “Compatibility”
Material Design 3Spec checked91% tokens

86 of 150 buildable spec units are tested, 5 are excluded with a written reason and 0 are uncovered (the target is 0). 53 of 58 token declarations match the spec (91%), and 5 have no spec token.

switch on m3.material.io (opens in a new tab) How compliance is measured

BaselineWidely availableChrome 124Edge 124Firefox 125Safari 17.4

The component’s own CSS and JavaScript rely only on web platform features that are Baseline widely available: it works in Chrome 124, Edge 124, Firefox 125, Safari 17.4 and later.

Newer features it uses where the browser has them (progressive enhancements):

Browser support Learn more about Baseline (opens in a new tab)

WAI-ARIAaxe and ARIA 1.3 passButtonCheckbox

Roles the component renders: button (opens in a new tab), checkbox (opens in a new tab), switch (opens in a new tab).

Follows the WAI-ARIA Authoring Practices: Button (opens in a new tab), Checkbox (opens in a new tab), Switch (opens in a new tab).

2 rendered states run through axe-core and the WAI-ARIA 1.3 role and attribute rules in a real browser, with no known gaps.

WAI-ARIA 1.3 (opens in a new tab) ARIA Authoring Practices (opens in a new tab) Accessibility

Lighthouse97 · 100 · 100 · 100
  • Performance
  • Accessibility
  • Best practices
  • SEO

Audits under 90:

  • Eliminate render-blocking resources
  • Minify JavaScript
  • Enable text compression
  • Network dependency tree
  • Render blocking requests

Lighthouse 12.8.2 (desktop, 2026-11-08) on the component alone: its first example on a page of its own, without this site's shell. The modules are the development build (not bundled or minified), so the performance score is indicative.

Open the test page About Lighthouse (opens in a new tab)

API reference

Link to “API reference”

<md-gb-switch>

Link to “<md-gb-switch>”

A Material Design component.

Properties

Link to “Properties”
Property Attribute Type Default
density
The density, from 0 (default) to -3. Each step down removes 4px from the state layer (40px); the track keeps its size and the touch target stays 48px. Values are clamped to that range. switch.md: don't apply density by default; let people opt in to a denser layout.		 density Density
required
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		 required boolean false
selected
Puts the switch in the selected state and sets the form submission value to the value property.		 selected boolean
value
The value associated with this switch on form submission. null is submitted when selected is false.		 value string 'on'

Slots

Link to “Slots”
Slot Description
off-icon Used to show an icon when the switch is unselected.
on-icon Used to show an icon when the switch is selected.

Events

Link to “Events”
Event Description
change
Event		 Fired when the switch is selected or unselected.
input
InputEvent		 Fired when the switch is selected or unselected.

CSS parts

Link to “CSS parts”
Part Description
::part(switch) The switch's root element.

CSS custom properties

Link to “CSS custom properties”
Property Description
--density-step State layer size removed per density step.
--handle-color
--handle-height
--handle-shape
--handle-width
--icon-color
--icon-size
--state-layer-color
--state-layer-shape
--state-layer-size State layer size at density 0.
--target-size The minimum touch target size, kept at any density.
--track-color
--track-height
--track-opacity
--track-outline-color
--track-outline-width
--track-shape
--track-width
--with-icon-handle-height
--with-icon-handle-width
Install Material Web 3.0

Your browser did not offer to install the docs as an app. Install them from the browser instead:

Close Send feedback
Bug Documentation Idea

Opens a new GitHub issue for material-components/material-web in a new tab, with this filled in.

Cancel Open issue