Anatomy
Note: Image not to scale
- Unchecked background fill
- Thumb (Indicator)
- Checked Background fill
- 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
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| defaultChecked | enum boolean | ---- | False | |
| asChild | enum boolean | ---- | False | |
| checked | enum boolean | ---- | False | |
| required | enum boolean | ---- | False | |
| onCheckedChange | (checked: boolean) => void | ---- | False | |
| variant | The `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. | enum cta | primary | ---- | False |
| error | enum boolean | true | false | ---- | False | |
| as | WPDS provides an as prop for changing which tag a component outputs. | never | ---- | False |
| css | WPDS 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
| Prop | Description | Type | Default | Required |
|---|---|---|---|---|
| asChild | enum boolean | ---- | False | |
| as | WPDS provides an as prop for changing which tag a component outputs. | never | ---- | False |
| css | WPDS 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 |