Skip to main content

Switch

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

In Dense data

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​

In Dense data: Settings that apply at once.

  • 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​

  • Lead with the object, then the state: "Alert 2041 contained."
  • Use numbers, not words for numbers.
  • One verb per button. No "please", no exclamation marks.
  • Use: Investigate, Filter, Assign, Escalated, Resolved. Avoid: Oops, Awesome, Please, Simply.

The labels components use, from the voice tokens:

  • content.action.commit: Save
  • content.action.cancel: Cancel
  • content.action.destroy: Delete
  • content.action.retry: Retry
  • content.action.empty-action: Change filters

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

Dense data 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)Lightviolet.light.600:#4B3FD9Darkviolet.dark.600:#A9A3F6
Control checked
Changes with theme
when on		component.control.checkedcolor.action.primaryvar(--control-checked)Lightviolet.light.600:#4B3FD9Darkviolet.dark.600:#A9A3F6
Control track
Changes with theme		component.control.trackcolor.border.strongvar(--control-track)Lightslate.light.500:#6B7585Darkslate.dark.400:#969FAD
Control thumb
Changes with theme		component.control.thumbcolor.surface.defaultvar(--control-thumb)Lightslate.light.0:#FFFFFFDarkslate.dark.50:#161B23
Transition durationcomponent.transition.durationmotion.duration.feedbackvar(--transition-duration)duration.fast:120ms
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.16:1rem
Widthcomponent.switch.widthsize.iconvar(--switch-width)size.16:1rem
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.2:2px
Disabled
when disabled		component.switch.disabledopacity.disabledvar(--switch-disabled)opacity.40:0.4
Canvas
Changes with theme
on focus		component.switch.canvascolor.surface.canvasvar(--switch-canvas)Lightslate.light.50:#F7F8FADarkslate.dark.0:#0D1117
Sizecomponent.switch.sizesize.iconvar(--switch-size)size.16:1rem
Icon
when on		component.switch.iconsize.iconvar(--switch-icon)size.16:1rem