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

<Switch aria-label="Switch example" />

<Switch aria-label="Switch example" />

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.

Always add a label to the switch.

Don't use switches without labels in forms.

Write unambiguous labels that start with a verb.

Don’t mix label styles.

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.

Label the column with the switch control.

Don’t group switches without labels with other actions.

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

<Switch id="switch-test" dataTestId="switch-custom-id" label="Switch me" labelPosition="right" />

<Switch
  id="switch-test"
  dataTestId="switch-custom-id"
  label="Switch me"
  labelPosition="right"
/>

Result

Loading...

Disabled

Live Editor

<> <Switch id="switch-disabled" disabled label="You can't switch me" labelPosition="right" /> </>

<>
  <Switch
    id="switch-disabled"
    disabled
    label="You can't switch me"
    labelPosition="right"
  />
</>

Result

Loading...

Size

Live Editor

<> <Switch size="small" aria-label="Small switch" label="Small" labelPosition="left" /> <Switch size="medium" aria-label="Medium switch" label="Medium" labelPosition="left" /> </>

<>
  <Switch
    size="small"
    aria-label="Small switch"
    label="Small"
    labelPosition="left"
  />
  <Switch
    size="medium"
    aria-label="Medium switch"
    label="Medium"
    labelPosition="left"
  />
</>

Result

Loading...

Props

Name	Type	Default
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.

Related components:

• Checkbox
• Radio