Skip to main content

Switch

A Switch is a visual toggle between two specific states — on and off. It shows that it's on when the accent color is visible and the switch is positioned to the right, and off when the switch has no accent color and is positioned to the left. The option represented by a Switch shall be immediately applied once the Switch state changes. There must not be an additional "save" or "apply" button.

Example

Live Editor
Result
Loading...

Usage Rules

Do:

  • Use a single Switch to toggle a single setting
  • Activate or deactivate an option immediately – no secondary steps required.
  • Use it when the choices are mutually exclusive

Don’t:

  • Toggle multiple settings with a single Switch
  • Use states that represent something other than on and off
  • Use a Switch in combination with an additional save or apply step
  • Change the switch label based on the state

Use concise and unambiguous labels

Switches must always have labels that describe what the control will do when the switch is on.

Labels should be short and direct. Write the labels in sentence case with a verb at the start. They should not be neutral or ambiguous.

Instead of asking questions, the option must be added as a statement, so that the user can agree and allow it or not. When in doubt, say the label aloud and append "on/off" to the end. If it doesn't make sense, then rewrite the label.

Use switches as actions in lists of items

Switches can be used in an overview of items to activate or deactivate a setting directly. Use small switches inside a table. As the switches used in forms, switches used in item lists must be labeled. Use the column header to label the switch control. Do not group switches with other actions in a column without a label of what the switch controls.

If a list of items has other statuses that cannot be represented only by the switch being on and off, display these in a separate column with badges representing the current status.

Provide appropriate feedback

Provide feedback while processing the change of state of the setting controlled by the Switch. Display a loading status indicator while waiting for the system to respond and change the Switch state after a successful response or keep its current state in case of a negative response. Display a toast accordingly to confirm the action or give instructions in case of an error.

Switches can be disabled

A Switch in a disabled state shows a possible selection that is not available in the current scenario. This can be used to maintain layout continuity, show that an action may become available later or to show an option that is dependent on a different toggle.

Before disabling a switch, consider the principle of progressive disclosure. By hiding the advanced settings, progressive disclosure helps users avoid mistakes and saves them the time they would have spent contemplating features that they don't need.

When disabling a switch, include a delayed tooltip on hover that explains why the control is unavailable at the moment.

Include a delayed tooltip when hovering disbled switches.

When to use: Switches vs. Checkboxes vs. Radio buttons

tip

Nielsen Norman created a chart to define in which cases we should use Radio buttons, a Checkbox or a Switch toggle. Read the article

Variants

Custom dataTestId

Live Editor
Result
Loading...

Disabled

Live Editor
Result
Loading...

Size

Live Editor
Result
Loading...

Props

NameTypeDefault
size
Size of the Switch
"small" | "medium"
"medium"
checked
A Boolean attribute indicating whether Switch is "turned on"
boolean
disabled
Native HTML attribute: Link
boolean
readOnly
Native HTML attribute: Link
boolean
onChange
Native HTML callback: Link
ChangeEventHandler<HTMLInputElement>
id
Native HTML attribute: Link . Internally, this component uses a random id. We use it to associate an input with a label element. As the random id might break snapshot tests it can be overridden by setting an explicit id.
string
aria-label
Provide at least one label(visual or non-visual) property for better accessibility. Check Accessibility page for more info: Link
string
aria-labelledby
Provide at least one label(visual or non-visual) property for better accessibility. Check Accessibility page for more info: Link
string
label
The label for the switch
string
labelPosition
The label position
"left" | "right"
"left"
dataTestId
Data-testid for the component
string
css
Add custom styles to this component. Use with caution. Learn more here: Link
SupportedStyleAttributes
inputFieldCss
SupportedStyleAttributes
data-{foo}
Data attributes can be used by testing libraries to retrieve components or assert their existence
string
* - the prop is required.