Skip to main contentSkip to docs navigation

Switch

Custom toggle component built on top of native <input> checkbox elements.

Layer: forms
View & Edit
On this page

Basic switch

Switches work by layering an invisible checkbox over the custom switch indicator. This preserves interactivity while giving you a completely customizable layer underneath. Switches also include the switch attribute for browsers that support it, which provides haptic feedback when toggling.

HTML
<div class="switch">
  <input type="checkbox" value="" id="switch" role="switch" switch>
</div>

With form field

Wrap the .switch in a .form-field layout wrapper and add your label. The grid layout places the switch and label side by side.

HTML
<div class="form-field">
  <div class="switch">
    <input type="checkbox" value="" id="switchMdLabel" role="switch" switch>
  </div>
  <label for="switchMdLabel">Default switch</label>
</div>

Disabled

Add the disabled attribute and the associated <label>s are automatically styled to match with a lighter color to help indicate the input’s state.

HTML
<div class="form-field">
  <div class="switch">
    <input type="checkbox" value="" id="switchDisabledLabel" role="switch" switch disabled>
  </div>
  <label for="switchDisabledLabel">Disabled switch</label>
</div>

<div class="form-field">
  <div class="switch">
    <input type="checkbox" value="" id="switchCheckedDisabledLabel" role="switch" switch disabled checked>
  </div>
  <label for="switchCheckedDisabledLabel">Disabled checked switch</label>
</div>

Sizes

Add a size modifier class to make your switch appear smaller or larger.

HTML
<div class="form-field">
  <div class="switch switch-sm">
    <input type="checkbox" value="" id="switchSizeSm" role="switch" switch>
  </div>
  <label for="switchSizeSm">Small switch</label>
</div>
<div class="form-field">
  <div class="switch">
    <input type="checkbox" value="" id="switchSizeMd" role="switch" switch>
  </div>
  <label for="switchSizeMd">Default switch</label>
</div>
<div class="form-field">
  <div class="switch switch-lg">
    <input type="checkbox" value="" id="switchSizeLg" role="switch" switch>
  </div>
  <label for="switchSizeLg">Large switch</label>
</div>

CSS

Variables

scss/forms/_switch.scss
// stylelint-disable-next-line scss/dollar-variable-default
$switch-tokens: defaults(
  (
    --switch-height: 1.25rem,
    --switch-width: calc(var(--switch-height) * 1.75),
    --switch-padding: .0625rem,
    --switch-margin-block: .125rem,
    // Share the form-control motion tokens so switch, checkbox, and radio move
    // in sync; the overshoot ("back") easing makes the thumb bounce as it settles.
    --switch-transition-duration: var(--control-transition-duration),
    --switch-transition-timing: var(--control-transition-timing),
    --switch-bg: var(--bg-3),
    --switch-border-width: var(--border-width),
    --switch-border-color: var(--border-color),
    --switch-indicator-bg: var(--white),
    --switch-indicator-width: calc(var(--switch-height) - calc(var(--switch-padding) * 2) - var(--switch-border-width) * 2),
    --switch-indicator-height: calc(var(--switch-height) - calc(var(--switch-padding) * 2) - var(--switch-border-width) * 2),
    --switch-checked-bg: var(--control-checked-bg),
    --switch-checked-border-color: var(--switch-checked-bg),
    --switch-checked-indicator-bg: var(--white),
    --switch-disabled-bg: var(--control-disabled-bg),
    --switch-disabled-indicator-bg: var(--fg-3),
  ),
  $switch-tokens
);