Switch

Material Design 3 toggle switch for binary on/off states with smooth animations and clear visual feedback. Not intended for multi-option selection; use checkboxes or radios for those scenarios.

Basic Usage

Use switches for binary settings. This is the recommended baseline because switches communicate on/off state more directly than a checkbox and apply the setting immediately without requiring a submit action. 

<ds-switch id="switch-basic" label="Enable alerts"></ds-switch>

Variants

Use icons when the state should be explicit.

With Icons

Shows a checkmark for the on state.

  • Use when: The on/off status needs extra clarity, especially in accessibility-sensitive contexts.
  • Avoid when: Simple context makes the state self-evident and icons would add visual noise. 
<ds-switch show-icons label="Off with icon"></ds-switch>
<ds-switch checked show-icons label="On with icon"></ds-switch>

Sizes

Use size to align with layout density.

<ds-switch size="sm" label="Small"></ds-switch>
<ds-switch size="md" label="Medium" checked></ds-switch>
<ds-switch size="lg" label="Large"></ds-switch>

States

Show on, off, and disabled states clearly.

On and Off

Default switch behavior with on and off states.

<ds-switch label="Off"></ds-switch>
<ds-switch checked label="On"></ds-switch>

Disabled

Switches can be disabled in both on and off states.

<ds-switch disabled label="Disabled off"></ds-switch>
<ds-switch checked disabled label="Disabled on"></ds-switch>

Interactive Example

Live example showing switches in a settings panel.

API

Attributes

Attribute Type Default Description
name string "" Form field name. The value, while on, is submitted under it; without a name the field is left out.
value string "on" Value submitted while the switch is on.
required boolean false Whether the switch must be on. Blocks the enclosing form's submission until satisfied.
checked boolean false Whether the switch is on.
disabled boolean false Whether the switch is disabled.
show-icons boolean false Whether to show the selected icon.
label string "" Label text rendered next to the control and mirrored into aria-label for its accessible name.
size string "" Size of the switch (sm, md, lg).

Forms

Submits its value (default "on") while on and nothing while off, like a native checkbox. required means it must be on. It resets with its form, and a disabled <fieldset> disables it. form, validity, validationMessage, checkValidity() and reportValidity() behave as on a native control.

Properties

Property Type Description
checked boolean Get or set the checked state.
disabled boolean Get or set the disabled state.
showIcons boolean Get or set whether icons are shown.
label string Get or set the label text.
size string Get or set the size.

Events

Event Detail Description
ds-switch:change { checked: boolean } Fired when the switch state changes.

Methods

Method Returns Description
toggle() void Toggle the switch state.

CSS Parts

Part Description
None.

CSS Custom Properties

Property Description
--md-sys-color-primary Track color for the on state.
--md-sys-color-on-primary Handle color for the on state.
--md-sys-color-outline Track border color for the off state.
--md-sys-color-surface-container-highest Track background for the off state.
--md-sys-color-on-surface Disabled state color.
--ds-shadow-1 Handle elevation shadow.
--ds-switch-track-width Track width (default: calc(var(--ds-switch-track-height, var(--ds-size-control-sm, 32px)) + 20px)).
--ds-switch-track-height Track height (default: var(--ds-size-control-sm, 32px)).
--ds-switch-icon-size Base icon size (default: var(--ds-size-icon-md, 18px)).
--ds-switch-state-layer-size State layer size (default: var(--ds-size-hit-area, 40px)).
--ds-switch-handle-size-off Handle size when off (default: calc(var(--ds-switch-icon-size) - 2px)).
--ds-switch-handle-size-on Handle size when on (default: calc(var(--ds-switch-icon-size) + 6px)).
--ds-switch-handle-size-pressed Handle size when pressed (default: calc(var(--ds-switch-icon-size) + 10px)).
--ds-switch-handle-icon-size Handle icon size (default: var(--ds-switch-icon-size)).

Accessibility

Keyboard Map

Key Context Expected Result
Tab Switch not focused Moves focus to the switch.
Space / Enter Switch focused Toggles on/off state and emits change event.

Semantics

  • Uses role="switch", aria-checked, and aria-disabled.
  • The label attribute is mirrored into aria-label so the switch's accessible name doesn't depend on an external, unassociated label element.
  • Screen readers announce the on/off state.
  • Visible focus indicator supports keyboard navigation.

Usage Guidelines

  • When to use: Immediately-applied binary settings such as notifications, dark mode, or Wi-Fi.
  • When not to use: Actions that need explicit confirmation before taking effect; use a button and dialog.
  • Composition: Always pair with a visible label so the setting is clear without interaction.
  • Common mistakes: Using switches for multi-select or non-binary choices, and omitting labels.