@material/switch

What is @material/switch?

@material/switch is a Material Design implementation of a switch component. It provides a customizable and accessible switch that can be used to toggle between two states, such as on and off. The package is part of the Material Components for the web, which ensures a consistent look and feel across different platforms.

What are @material/switch's main functionalities?

Basic Switch

This is the most basic usage of the @material/switch component. It renders a switch that can be toggled between on and off states.

<mwc-switch></mwc-switch>

Disabled Switch

This example shows how to render a switch that is disabled and cannot be interacted with.

<mwc-switch disabled></mwc-switch>

Switch with Label

This example demonstrates how to use a switch with a label. The label is provided using the mwc-formfield component.

<mwc-formfield label="Toggle me"><mwc-switch></mwc-switch></mwc-formfield>

Switch with Event Listener

This example shows how to add an event listener to the switch to handle state changes.

document.querySelector('mwc-switch').addEventListener('change', (e) => { console.log('Switch state:', e.target.checked); });

Other packages similar to @material/switch

react-switch

react-switch is a lightweight switch component for React. It provides similar functionality to @material/switch but is designed specifically for React applications. It offers customization options for colors, sizes, and labels.

rc-switch

rc-switch is a React component that provides a switch UI element. It is highly customizable and supports various themes and styles. It is similar to @material/switch but is more focused on providing a flexible API for React developers.

vue-js-toggle-button

vue-js-toggle-button is a Vue.js component for creating toggle buttons. It offers similar functionality to @material/switch but is designed for Vue.js applications. It supports customization of colors, sizes, and labels.

README

Selection controls: switches

Selection controls allow the user to select options.

Switches toggle the state of a single setting on or off. They are the preferred way to adjust settings on mobile.

Contents

• Using switches
• Switches
• Other variants
• API
• Usage within web frameworks

Using switches

Use switches to:

• Toggle a single item on or off, on mobile and tablet
• Immediately activate or deactivate something

Installing switches

npm install @material/switch

Styles

@use '@material/switch/styles';

JavaScript instantiation

The switch requires JavaScript to function, so it is necessary to instantiate MDCSwitch on the mdc-switch element.

import {MDCSwitch} from '@material/switch';

for (const el of document.querySelectorAll('.mdc-switch')) {
  const switchControl = new MDCSwitch(el);
}

Note: See Importing the JS component for more information on how to import JavaScript.

Switches

Switch example

<button id="basic-switch" class="mdc-switch mdc-switch--unselected" type="button" role="switch" aria-checked="false">
  <div class="mdc-switch__track"></div>
  <div class="mdc-switch__handle-track">
    <div class="mdc-switch__handle">
      <div class="mdc-switch__shadow">
        <div class="mdc-elevation-overlay"></div>
      </div>
      <div class="mdc-switch__ripple"></div>
      <div class="mdc-switch__icons">
        <svg class="mdc-switch__icon mdc-switch__icon--on" viewBox="0 0 24 24">
          <path d="M19.69,5.23L8.96,15.96l-4.23-4.23L2.96,13.5l6,6L21.46,7L19.69,5.23z" />
        </svg>
        <svg class="mdc-switch__icon mdc-switch__icon--off" viewBox="0 0 24 24">
          <path d="M20 13H4v-2h16v2z" />
        </svg>
      </div>
    </div>
  </div>
  <span class="mdc-switch__focus-ring-wrapper">
    <div class="mdc-switch__focus-ring"></div>
  </span>
</button>
<label for="basic-switch">off/on</label>

The mdc-switch__focus-ring element ensures that a focus indicator is displayed in high contrast mode around the active/focused switch.

Switch states

Switches can be on or off. Switches have enabled, hover, focused, and pressed states.

Other variants

Initially disabled switch

Add the disabled attribute to the mdc-switch element to disable the switch. This logic is handled by the MDCSwitch.disabled property, but you'll want to avoid a FOUC by initially adding this attribute.

<button id="disabled-switch" class="mdc-switch mdc-switch--unselected" type="button" role="switch" aria-checked="false" disabled>
  <div class="mdc-switch__track"></div>
  <div class="mdc-switch__handle-track">
    <div class="mdc-switch__handle">
      <div class="mdc-switch__shadow">
        <div class="mdc-elevation-overlay"></div>
      </div>
      <div class="mdc-switch__ripple"></div>
      <div class="mdc-switch__icons">
        <svg class="mdc-switch__icon mdc-switch__icon--on" viewBox="0 0 24 24">
          <path d="M19.69,5.23L8.96,15.96l-4.23-4.23L2.96,13.5l6,6L21.46,7L19.69,5.23z" />
        </svg>
        <svg class="mdc-switch__icon mdc-switch__icon--off" viewBox="0 0 24 24">
          <path d="M20 13H4v-2h16v2z" />
        </svg>
      </div>
    </div>
  </div>
  <span class="mdc-switch__focus-ring-wrapper">
    <div class="mdc-switch__focus-ring"></div>
  </span>
</button>
<label for="disabled-switch">off/on</label>

Initially "on" switch

Add the mdc-switch--selected class and aria-checked="true" attribute to the mdc-switch element to toggle the switch to "on". This logic is handled by the MDCSwitch.selected method, but you'll want to avoid a FOUC by initially adding this class and attribute.

<button id="selected-switch" class="mdc-switch mdc-switch--selected" type="button" role="switch" aria-checked="true">
  <div class="mdc-switch__track"></div>
  <div class="mdc-switch__handle-track">
    <div class="mdc-switch__handle">
      <div class="mdc-switch__shadow">
        <div class="mdc-elevation-overlay"></div>
      </div>
      <div class="mdc-switch__ripple"></div>
      <div class="mdc-switch__icons">
        <svg class="mdc-switch__icon mdc-switch__icon--on" viewBox="0 0 24 24">
          <path d="M19.69,5.23L8.96,15.96l-4.23-4.23L2.96,13.5l6,6L21.46,7L19.69,5.23z" />
        </svg>
        <svg class="mdc-switch__icon mdc-switch__icon--off" viewBox="0 0 24 24">
          <path d="M20 13H4v-2h16v2z" />
        </svg>
      </div>
    </div>
  </div>
  <span class="mdc-switch__focus-ring-wrapper">
    <div class="mdc-switch__focus-ring"></div>
  </span>
</button>
<label for="selected-switch">off/on</label>

API

CSS classes

CSS Class	Description
mdc-switch	Mandatory, for the parent element.
mdc-switch--unselected	Optional, styles the switch as unselected ("off")
mdc-switch--selected	Optional, styles the switch as selected ("on")
mdc-switch__track	Mandatory, for the track element.
mdc-switch__handle-track	Mandatory, for the handle's track element.
mdc-switch__handle	Mandatory, for the handle element.
mdc-switch__shadow	Mandatory, for the shadow effect.
mdc-elevation-overlay	Mandatory, for the shadow effect's overlay in dark mode.
mdc-switch__ripple	Mandatory, for the ripple effect.
mdc-switch__icons	Mandatory, for the icons.
mdc-switch__icon	Mandatory, for the icon elements.
mdc-switch__icon--on	Mandatory, for the on icon.
mdc-switch__icon--off	Mandatory, for the off icon.

Theme mixin

The switch may be customized using the theme() mixin and providing an MDC Theme string (such as primary) or other values to the theme keys.

@use '@material/switch';
@use '@material/theme/color-palette';
@use '@material/theme/shadow-dom';

// Include for IE11 support
// @include shadow-dom.enable-css-selector-fallback-declarations(true);

.my-switch {
  @include switch.theme((
    selected-handle-color: color-palette.$teal-600,
    selected-track-color: color-palette.$teal-300,
  ));
}

View the theme file for available keys and built-in themes.

MDCSwitch properties

Property	Value Type	Description
disabled	Boolean	Indicates whether or not the switch is disabled.
selected	Boolean	If true, the switch is on. If false, the switch is off.

Usage within web frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a switch for your framework. Depending on your needs, you can use the Simple Approach: Wrapping MDC Web Vanilla Components, or the Advanced Approach: Using Foundations and Adapters. Please follow the instructions here.

See MDCSwitchAdapter and MDCSwitchFoundation for up-to-date code documentation of switch's foundation API.