Skip to content
Edit this page

Switch

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

Switches are the preferred way to adjust 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.

Basic switches

<Switch {...label} defaultChecked />
<Switch {...label} />
<Switch {...label} disabled defaultChecked />
<Switch {...label} disabled />

Label

You can provide a label to the Switch thanks to the FormControlLabel component.

<FormGroup>
  <FormControlLabel control={<Switch defaultChecked />} label="Label" />
  <FormControlLabel disabled control={<Switch />} label="Disabled" />
</FormGroup>

Size

Use the size prop to change the size of the switch.

<Switch {...label} defaultChecked size="small" />
<Switch {...label} defaultChecked />

Color

<Switch {...label} defaultChecked />
<Switch {...label} defaultChecked color="secondary" />
<Switch {...label} defaultChecked color="warning" />
<Switch {...label} defaultChecked color="default" />
<GreenSwitch {...label} defaultChecked />

Controlled

You can control the switch with the checked and onChange props:

<Switch
  checked={checked}
  onChange={handleChange}
  inputProps={{ 'aria-label': 'controlled' }}
/>

Switches with FormGroup

FormGroup is a helpful wrapper used to group selection controls components that provides an easier API. However, you are encouraged to use Checkboxes instead if multiple related controls are required. (See: When to use).

Assign responsibility

Be careful

Customization

Here are some examples of customizing the component. You can learn more about this in the overrides documentation page.

Off

On

🎨 If you are looking for inspiration, you can check MUI Treasury's customization examples.

Unstyled

The switch also comes with an unstyled version. It's ideal for doing heavy customizations and minimizing bundle size.

import SwitchUnstyled from '@mui/base/SwitchUnstyled';

The SwitchUnstyled component provides default components and assigns CSS classes you can style entirely on your own. You are free to choose any styling solution - plain CSS classes, a CSS framework, Emotion, etc. It is also possible to replace these default components by other HTML elements or custom components.

There are three components you can override by the components prop: Root, Thumb and Input. Each one's props can be set using the componentsProps object.

<SwitchUnstyled component={Root} {...label} defaultChecked />
<SwitchUnstyled component={Root} {...label} />
<SwitchUnstyled component={Root} {...label} defaultChecked disabled />
<SwitchUnstyled component={Root} {...label} disabled />

useSwitch hook

For the ultimate customizability, a useSwitch hook is available. It accepts almost the same options as the SwitchUnstyled component minus the component, components, and componentsProps props.

import { useSwitch } from '@mui/base/SwitchUnstyled';

Basic example

<BasicSwitch defaultChecked />
<BasicSwitch />
<BasicSwitch defaultChecked disabled />
<BasicSwitch disabled />

Customized look and feel

<MUISwitch defaultChecked />

Label placement

You can change the placement of the label:

Label placement

When to use

Accessibility

  • It will render an element with the checkbox role not switch role since this role isn't widely supported yet. Please test first if assistive technology of your target audience supports this role properly. Then you can change the role with <Switch inputProps={{ role: 'switch' }}>
  • All form controls should have labels, and this includes radio buttons, checkboxes, and switches. In most cases, this is done by using the <label> element (FormControlLabel).
  • When a label can't be used, it's necessary to add an attribute directly to the input component. In this case, you can apply the additional attribute (e.g. aria-label, aria-labelledby, title) via the inputProps prop.
<Switch value="checkedA" inputProps={{ 'aria-label': 'Switch A' }} />

API