Switch

Switches toggle the state of a single setting on or off.

Introduction

Switches are very commonly used for adjusting settings on mobile. The option that the switch controls, as well as the state it's in, should be made clear from the corresponding inline label.

Component

After installation, you can start building with this component using the following basic elements:

import Switch from '@mui/joy/Switch';

export default function MyApp() {
  return <Switch />;
}

Controlled

To create a controlled switch, use the checked and onChange props.

Label

When a Switch is used together with FormControl and FormLabel, the switch is labelled automatically. You can also use FormHelperText to include a description to the switch as well.

An alternative way is to place the Switch component inside a label element. The Typography is used in this case to leverage the typography scale from the theme.

Decorators

To insert icon decorators, use the startDecorator and/or endDecorator props.

Track child

Target the track's children using the slotProps prop to display a text inside of it.

Thumb child

Similarly to the above, target the thumb's children to display icons inside of it.

CSS variables playground

Play around with all the CSS variables available in the switch component to see how the design changes.

You can use those to customize the component on both the sx prop and the theme.

Common examples

Fluent UI

Here's how you'd customize Joy UI's Switch to make it look like Microsoft's Fluent UI:

• Unchecked state: outlined variant and neutral color.
• Checked state: solid variant and primary color.

iOS

Note how we've used the :active pseudo-class to replicate the small thumb size increase, which happens when you press and hold the switch.

Strapi

Chakra UI

Tailwind UI

Mantine

Accessibility

Here are a few tips to make sure you have an accessible switch component:

• The Switch will render with the checkbox role as opposed to switch. This is mainly because the latter isn't widely supported yet. However, if you believe your audience will support it, make sure to test with assistive technology. Use the slotProps prop to change the role:

  <Switch slotProps={{ input: { role: 'switch' } }}>
  

  (or $keyC)

• Every form control component should have proper labels. This includes radio buttons, checkboxes, and switches. In most cases, this is done using the <label> element.

  • If a label can't be applied, make sure to add an attribute (e.g. aria-label, aria-labelledby, title) to the input slot inside the slotProps prop.

  <Switch value="checkedA" slotProps={{ 'aria-label': 'Switch A' }} />
  

  (or $keyC)

Unstyled

Use the Base UI Switch for complete ownership of the component's design, with no Material UI styles to override. This unstyled version of the component is the ideal choice for heavy customization with a smaller bundle size.

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

• <Switch />