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 @loipham/material-switch

Styles

@use '@loipham/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 '@loipham/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 '@loipham/material-switch';
@use '@loipham/material-theme/color-palette';
@use '@loipham/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.