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:

<span class="token keyword">import</span> Switch <span class="token keyword">from</span> <span class="token string">'@mui/joy/Switch'</span><span class="token punctuation">;</span>

<span class="token keyword">export</span> <span class="token keyword">default</span> <span class="token keyword">function</span> <span class="token function">MyApp</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token keyword">return</span> <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Switch</span></span> <span class="token punctuation">/></span></span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

Controlled

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

<Switch
  checked={checked}
  onChange={(event) => setChecked(event.target.checked)}
/>

<Switch
  checked={checked}
  onChange={(event) => setChecked(event.target.checked)}
/>

Press Enter to start editing

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.

Show captions

All languages available.

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.

Turn alarm on

<Typography component="label" endDecorator={<Switch sx={{ ml: 1 }} />}>
  Turn alarm on
</Typography>

<Typography component="label" endDecorator={<Switch sx={{ ml: 1 }} />}>
  Turn alarm on
</Typography>

Press Enter to start editing

Decorators

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

<Switch
  color={dark ? 'primary' : 'danger'}
  slotProps={{ input: { 'aria-label': 'dark mode' } }}
  startDecorator={
    <LocalFireDepartmentRoundedIcon
      sx={{ color: dark ? 'text.tertiary' : 'danger.600' }}
    />
  }
  endDecorator={
    <WavesRoundedIcon sx={{ color: dark ? 'primary.500' : 'text.tertiary' }} />
  }
  checked={dark}
  onChange={(event: React.ChangeEvent<HTMLInputElement>) =>
    setDark(event.target.checked)
  }
/>

<Switch
  color={dark ? 'primary' : 'danger'}
  slotProps={{ input: { 'aria-label': 'dark mode' } }}
  startDecorator={
    <LocalFireDepartmentRoundedIcon
      sx={{ color: dark ? 'text.tertiary' : 'danger.600' }}
    />
  }
  endDecorator={
    <WavesRoundedIcon sx={{ color: dark ? 'primary.500' : 'text.tertiary' }} />
  }
  checked={dark}
  onChange={(event: React.ChangeEvent<HTMLInputElement>) =>
    setDark(event.target.checked)
  }
/>

Press Enter to start editing

Track child

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

OnOff

Thumb child

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

<Switch
  slotProps={{
    input: { 'aria-label': 'Dark mode' },
    thumb: {
      children: <DarkMode />,
    },
  }}
  sx={{
    '--Switch-thumbSize': '28px',
  }}
/>

<Switch
  slotProps={{
    input: { 'aria-label': 'Dark mode' },
    thumb: {
      children: <DarkMode />,
    },
  }}
  sx={{
    '--Switch-thumbSize': '28px',
  }}
/>

Press Enter to start editing

CSS Variables

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.

<Switch />

CSS Variables

--Switch-gap

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:

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Switch</span></span> <span class="token attr-name">slotProps</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">input</span><span class="token operator">:</span> <span class="token punctuation">{</span> <span class="token literal-property property">role</span><span class="token operator">:</span> <span class="token string">'switch'</span> <span class="token punctuation">}</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span><span class="token punctuation">></span></span>

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.

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Switch</span></span> <span class="token attr-name">value</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>checkedA<span class="token punctuation">"</span></span> <span class="token attr-name">slotProps</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token string-property property">'aria-label'</span><span class="token operator">:</span> <span class="token string">'Switch A'</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span>

Common examples

Material Design

You can also find the Material Design switch design, out of the box, in Material UI's documentation.

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

Unstyled

API

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

<Switch />

Switch

Introduction

Playground

Component

Controlled

Label

Decorators

Track child

Thumb child

CSS Variables

Accessibility

Common examples

Material Design

Fluent UI

iOS

Strapi

Chakra UI

Tailwind UI

Mantine

Unstyled

API