Skip to main content

Switch

Toggle on/off switch built on <input type="checkbox"> with role="switch". Renders as a pill-shaped track with a sliding thumb. Used for boolean settings that take effect immediately (not form submissions) - notifications on/off, dark mode on/off, auto-save on/off.

Usage​

When to use

  • Boolean settings that apply immediately on toggle
  • Feature toggles and preference controls
  • Any on/off state where a checkbox would feel like a form submission

When not to use

  • Part of a form that requires a submit action - use a checkbox
  • More than two states - use radio buttons or a segmented control
  • Mutually exclusive choices between labeled options - use radio buttons

Do

  • Associate a <label> with the switch via for/id
  • Reflect the current state via aria-checked (automatic on <input type="checkbox">)
  • Honor prefers-reduced-motion for the thumb animation

Don't

  • Use a switch to submit a form
  • Rely on color alone to communicate state
  • Build a custom div-based switch - use the native checkbox

API​

Slots​

SlotRequiredDescription
labelYesVisible label text for the switch.

Props​

PropTypeDefaultDescription
namestring-Name attribute for form submission.
idstring-Associates the control with its label.
is_checkedboolean-Sets the initial checked state.
is_disabledboolean-Disables the control.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.

Examples​

Sizes​

Sm, default, and lg variants stacked vertically. The track and thumb scale together.

Checked​

Pre-checked switch demonstrating the "on" treatment.

Wrapping​

The consumer-authored <label><input type="checkbox" role="switch"> Text</label> form. Semetrika's twig template emits the sibling form (<input> + <label>), but page authors and CMS integrations may hand-write the wrapping form. The wrapping label renders as inline-flex with align-items: center so the pill and the surrounding text share a true vertical center.

Disabled​

Disabled switch via the disabled attribute.

Accessibility​

  • WCAG 2.2 AA
  • role="switch" on the checkbox input
  • aria-checked reflects the toggle state (native checkbox state is exposed automatically)
  • Visible focus ring for keyboard users
  • Label association via <label> element
  • disabled attribute for disabled state
  • Animation respects prefers-reduced-motion
  • checkbox - alternative boolean control inside forms