Skip to main content
Design system

Switch

A visual control that allows the user to toggle between a binary state of “on” and “off”.

Bundle size: 10.59 kB
Install:
npm install @washingtonpost/wpds-ui-kit
|Copy
Usage:
import { Switch } from "@washingtonpost/wpds-ui-kit"
|Copy
Storybook:  View on Storybook
Source:  View on Github
Primitive:  View their docs

Anatomy

Note: Image not to scale

  1. Unchecked background fill
  2. Thumb (Indicator)
  3. Checked Background fill
  4. Border

Options

Variant

Two variants are supported primary and cta


Behavior

Checked

When the switch is checked it will transition to the on position.

Error

When the switch is a requirement it will show an error border color.

Required

No visual indication when required. See guidance on required switches

Disabled

Disable the switch when it is not editable. Disabled switches cannot be clicked.

Focus

When the switch is in focus a outline with the color signal will appear around the switch. Tab into the switch to see the focus state.


Guidance

Required Switches

When making switches required always pair it with a label that has the required indicator.

Switches control binary options

Don’t use switches to control states that cannot clearly be categorized as either on or off.

Label Pairing

Switches should always be paired with a contextual label. It is also good practice for accessibility to have a text equivalent of the state (on or off) is displayed adjacent to the graphical state indicator.


Accessibility

Space / Enter toggles switch

When the switch is in focus and the user presses space or enter it will toggle the switch from its current check state to the opposite state.

Pairing label

To make understanding the state of the switch easier for users with visual or cognitive disabilities, a text equivalent of the state (on or off) is displayed adjacent to the graphical state indicator. CSS attribute selectors ensure the label displayed is synchronized with the value of the aria-checked attribute.

NOTE: To prevent redundant announcement of the state by screen readers, the text indicators of state are hidden from assistive technologies with aria-hidden.

Cursor

Switches should have the cursor switch to pointer when the cursor is hovering over the switch.

Non-Text Contrast

For active controls any visual information provided that is necessary for a user to identify that a control is present and how to operate it must have a minimum 3:1 contrast ratio with the adjacent colors. Also, any visual information necessary to indicate state, such as whether a component is selected or focused must also ensure that the information used to identify the control in that state has a minimum 3:1 contrast ratio. - W3.org

Note: Image not to scale

Reduce motion

If user has indicated that they prefer reduced motion the switch thumb should not animate and instantly position to its enabled/disabled position.


API Reference

SwitchRoot

PropDescriptionTypeDefaultRequired
defaultChecked
boolean
----False
asChild
boolean
----False
checked
boolean
----False
required
boolean
----False
onCheckedChange
(checked: boolean) => void
----False
variantThe `variant` prop is used to set the color of the switch. The `primary` variant is the default. The `cta` variant is used for the call to action switch. The `primary` and `cta` variants are set in the `theme.colors` object. Switch.Thumb inherits the color of the `primary` and `cta` variants from Switch.Root using the `$$switchRootVariant` variable and the `$$switchThumbVariant` variable.
"cta" | "primary" | ({ "@reducedMotion"?: "cta" | "primary"; "@sm"?: "cta" | "primary"; "@md"?: "cta" | "primary"; "@lg"?: "cta" | "primary"; "@xl"?: "cta" | "primary"; "@xxl"?: "cta" | "primary"; ... 18 more ...; "@initial"?: "cta" | "primary"; } & { ...; })
----False
error
boolean | "true" | "false" | ({ "@reducedMotion"?: boolean | "true" | "false"; "@sm"?: boolean | "true" | "false"; "@md"?: boolean | "true" | "false"; "@lg"?: boolean | "true" | "false"; ... 20 more ...; "@initial"?: boolean | ... 1 more ... | "false"; } & { ...; })
----False
asWPDS provides an as prop for changing which tag a component outputs.
never
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS<{ sm: `(max-width: ${string})`; md: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; lg: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xxl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; notS...
----False

SwitchThumb

PropDescriptionTypeDefaultRequired
asChild
boolean
----False
asWPDS provides an as prop for changing which tag a component outputs.
never
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS<{ sm: `(max-width: ${string})`; md: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; lg: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; xxl: `(min-width: calc(${string} + 1px)) and (max-width: ${string})`; notS...
----False
Edit this page on GitHub.