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
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.
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
Disabled
Size
Props
Name | Type | Default |
---|---|---|
size Size of the Switch |
| "medium" |
checked A Boolean attribute indicating whether Switch is "turned on" |
| — |
disabled Native HTML attribute: Link |
| — |
readOnly Native HTML attribute: Link |
| — |
onChange Native HTML callback: Link |
| — |
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. |
| — |
aria-label Provide at least one label(visual or non-visual) property for better accessibility. Check Accessibility page for more info: Link |
| — |
aria-labelledby Provide at least one label(visual or non-visual) property for better accessibility. Check Accessibility page for more info: Link |
| — |
label The label for the switch |
| — |
labelPosition The label position |
| "left" |
dataTestId Data-testid for the component |
| — |
css Add custom styles to this component. Use with caution. Learn more here: Link |
| — |
inputFieldCss |
| — |
data-{foo} Data attributes can be used by testing libraries to retrieve components or assert their existence |
| — |
* - the prop is required. |