@material/switch

14.0.0 • Public • Published

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.

Switch hero example for menu options

Contents

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.

Switch states in a table. Columns are enabled, disabled, hover, focused, pressed. Rows are on or off.

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.

Versions

Current Tags

Version History

Package Sidebar

Install

npm i @material/switch

Weekly Downloads

850,886

Version

14.0.0

License

MIT

Unpacked Size

745 kB

Total Files

57

Last publish

Collaborators

  • material-admin
  • yefim
  • abhiomkar
  • azakus
  • bicknellr
  • aprigogin
  • patrickrodee
  • aomarks
  • emarquez
  • esgonzalez
  • asyncliz
  • candysonya
  • ssuarez
  • taylorv