Skip to main content

Switch

An on or off setting that applies at once, with no submit.

Left out of Accessible first Components do their work in forms and steps, where a choice waits for the form. The catalogue gives that case to the checkbox. Use instead: Checkbox

See it live​

Start Storybook to see it live: npm run storybook
Live from StorybookOpen Switch in StorybookSee it in dark

When to use it​

  • Use it when: A setting that should take effect as soon as it is flipped.
  • Not when: A choice that waits for a form (checkbox).

Instead:

  • Checkbox: Waits for the form.
  • Toggle: A pressed button in a toolbar.

Words​

  • Use common words. Explain any term you must use.
  • One idea per sentence. Put the action first.
  • Never blame the person.
  • Use: Continue, Change, Start, You. Avoid: Invalid, Utilise, Submit, Error code.

The labels components use, from the voice tokens:

  • content.action.commit: Continue
  • content.action.cancel: Go back
  • content.action.destroy: Delete
  • content.action.retry: Try again
  • content.action.empty-action: Start a new application

See Voice and tone for the whole voice.

Accessibility and keyboard​

KeyboardWhat happensNot
undefinedSpace flips it.undefined

Test before you ship:

  • It is a switch with a visible label; on and off are announced. undefined

Use it in code​

npx open-ds add switch

The component reads only component keys and semantic tokens, so it follows the brand and mode on <html>.

Tokens it reads​

Switch reads 15 tokens of its own, each an alias of a semantic token. Each row is one part: its own token, the semantic it aliases, and the value it ends at. Change a semantic and every component that reads it follows; override one of Switch's tokens to change Switch alone.

Changes with theme

Accessible first decides what changes when you switch theme. Here a switch changes colors only, so the marked rows differ between light and dark; everything else holds steady.

PartIts token and the semantic it aliasesValue
Shared
Button focus ring
Changes with theme
on focus		component.button.focus-ringcolor.border.focusvar(--button-focus-ring)Lightblue.light.600:#0B4FC0Darkblue.dark.600:#8AB4F8
Control checked
Changes with theme
when on		component.control.checkedcolor.action.primaryvar(--control-checked)Lightblue.light.600:#0B4FC0Darkblue.dark.600:#8AB4F8
Control track
Changes with theme		component.control.trackcolor.border.strongvar(--control-track)Lightgray.light.500:#595959Darkgray.dark.500:#949494
Control thumb
Changes with theme		component.control.thumbcolor.surface.defaultvar(--control-thumb)Lightgray.light.0:#FFFFFFDarkgray.dark.50:#141414
Transition durationcomponent.transition.durationmotion.duration.feedbackvar(--transition-duration)duration.moderate:200ms
Transition easingcomponent.transition.easingmotion.easing.standardvar(--transition-easing)easing.standard:cubic-bezier(0.2,0,0,1)
Switch
Heightcomponent.switch.heightsize.iconvar(--switch-height)size.20:1.25rem
Widthcomponent.switch.widthsize.iconvar(--switch-width)size.20:1.25rem
Cornercomponent.switch.radiusradius.roundvar(--switch-radius)radius.full:9999px
Paddingcomponent.switch.paddingcomponent-spacing-map.hairlinevar(--switch-padding)space.2:0.125rem
Focus
on focus		component.switch.focusborder-width.focusvar(--switch-focus)border-width.3:3px
Disabled
when disabled		component.switch.disabledopacity.disabledvar(--switch-disabled)opacity.50:0.5
Canvas
Changes with theme
on focus		component.switch.canvascolor.surface.canvasvar(--switch-canvas)Lightgray.light.50:#F7F7F7Darkgray.dark.0:#0A0A0A
Sizecomponent.switch.sizesize.iconvar(--switch-size)size.20:1.25rem
Icon
when on		component.switch.iconsize.iconvar(--switch-icon)size.20:1.25rem