@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

Switches

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

Design & API Documentation

• Material Design guidelines: Switches
• Demo

Installation

npm install @material/switch

Basic Usage

HTML Structure

<div class="mdc-switch">
  <div class="mdc-switch__track"></div>
  <div class="mdc-switch__thumb-underlay">
    <div class="mdc-switch__thumb">
        <input type="checkbox" id="basic-switch" class="mdc-switch__native-control" role="switch">
    </div>
  </div>
</div>
<label for="basic-switch">off/on</label>

Styles

@import "@material/switch/mdc-switch";

JavaScript Instantiation

The Switch requires JavaScript to function, so it is necessary to instantiate MDCSwitch with the HTML.

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

const switchControl = new MDCSwitch(document.querySelector('.mdc-switch'));

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

Variant

Initially Disabled Switch

Add the mdc-switch--disabled class to the mdc-switch element, and the disabled attribute to the mdc-switch__native-control element to disable the switch. This logic is handled by the MDCSwitchFoundation.setDisabled method, but you'll want to avoid a FOUC by initially adding this class and attribute.

<div class="mdc-switch mdc-switch--disabled">
  <div class="mdc-switch__track"></div>
  <div class="mdc-switch__thumb-underlay">
    <div class="mdc-switch__thumb">
      <input type="checkbox" id="another-basic-switch" class="mdc-switch__native-control" role="switch" disabled>
    </div>
  </div>
</div>
<label for="another-basic-switch">off/on</label>

Initially "On" Switch

Add the mdc-switch--checked class to the mdc-switch element, and the checked attribute to the mdc-switch__native-control element to toggle the switch to "on". This logic is handled by the MDCSwitchFoundation.setChecked method, but you'll want to avoid a FOUC by initially adding this class and attribute.

<div class="mdc-switch mdc-switch--checked">
  <div class="mdc-switch__track"></div>
  <div class="mdc-switch__thumb-underlay">
    <div class="mdc-switch__thumb">
      <input type="checkbox" id="another-basic-switch" class="mdc-switch__native-control" role="switch" checked>
    </div>
  </div>
</div>
<label for="another-basic-switch">off/on</label>

Style Customization

CSS Classes

CSS Class	Description
mdc-switch	Mandatory, for the parent element.
mdc-switch--disabled	Optional, styles the switch as disabled
mdc-switch--checked	Optional, styles the switch as checked ("on")
mdc-switch__track	Mandatory, for the track element.
mdc-switch__thumb-underlay	Mandatory, for the ripple effect.
mdc-switch__thumb	Mandatory, for the thumb element.
mdc-switch__native-control	Mandatory, for the hidden input checkbox.

Sass Mixins

MDC Switch uses MDC Theme's secondary color by default for the checked (toggled on) state. Use the following mixins to customize enabled switches. It is not currently possible to customize the color of a disabled switch. Disabled switches use the same colors as enabled switches, but with a different opacity value.

Mixin	Description
mdc-switch-toggled-on-color($color)	Sets the base color of the track, thumb, and ripple when the switch is toggled on.
mdc-switch-toggled-off-color($color)	Sets the base color of the track, thumb, and ripple when the switch is toggled off.
mdc-switch-toggled-on-track-color($color)	Sets color of the track when the switch is toggled on.
mdc-switch-toggled-off-track-color($color)	Sets color of the track when the switch is toggled off.
mdc-switch-toggled-on-thumb-color($color)	Sets color of the thumb when the switch is toggled on.
mdc-switch-toggled-off-thumb-color($color)	Sets color of the thumb when the switch is toggled off.
mdc-switch-toggled-on-ripple-color($color)	Sets the color of the ripple surrounding the thumb when the switch is toggled on.
mdc-switch-toggled-off-ripple-color($color)	Sets the color of the ripple surrounding the thumb when the switch is toggled off.
mdc-switch-ripple-size($ripple-size)	Sets the ripple size of the switch.
mdc-switch-density($density-scale)	Sets density scale for switch. Supported density scales are -5, -4, -3, -2, -1, and 0 (default).
mdc-switch-ripple-states-opacity($opacity-map)	Sets the opacity of the ripple surrounding the thumb in any of the hover, focus, or press states. The opacity-map can specify any of these states as keys. States not specified in the map resort to default opacity values.

MDCSwitch Properties and Methods

Property	Value Type	Description
checked	Boolean	Setter/getter for the switch's checked state
disabled	Boolean	Setter/getter for the switch's disabled state

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.

MDCSwitchAdapter

Method Signature	Description
addClass(className: string) => void	Adds a class to the root element.
removeClass(className: string) => void	Removes a class from the root element.
setNativeControlChecked(checked: boolean)	Sets the checked state of the native control.
setNativeControlDisabled(disabled: boolean)	Sets the disabled state of the native control.

MDCSwitchFoundation

Method Signature	Description
setChecked(checked: boolean) => void	Sets the checked value of the native control and updates styling to reflect the checked state.
setDisabled(disabled: boolean) => void	Sets the disabled value of the native control and updates styling to reflect the disabled state.
handleChange(evt: Event) => void	Handles a change event from the native control.

MDCSwitchFoundation Event Handlers

If wrapping the switch component it is necessary to add an event handler for native control change events that calls the handleChange foundation method. For an example of this, see the MDCSwitch component's initialSyncWithDOM method.

Event	Element Selector	Foundation Handler
change	.mdc-switch__native-control	handleChange()