Unstyled Switch

Switches are UI elements that let users choose between two states—most commonly on/off.

Introduction

The Unstyled Switch component provides users with a switch for toggling between two mutually exclusive states.

Component

Usage

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

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

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

Basics

The following demo shows how to assign styles and props to the Unstyled Switch component:

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

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

Press Enter to start editing

Anatomy

The Unstyled Switch component is composed of a root <span> that houses three interior slots—a track, a thumb, and an input:

<span class="MuiSwitch-root">
  <span class="MuiSwitch-track"></span>
  <span class="MuiSwitch-thumb"></span>
  <input type="checkbox" class="MuiSwitch-input" />
</span>

Slot props

Use the component prop to override the root slot with a custom element:

<SwitchUnstyled component="div" />

Use the slots prop to override any interior slots in addition to the root:

<SwitchUnstyled slots={{ root: 'div', track: 'div' }} />

Use the slotProps prop to pass custom props to internal slots. The following code snippet applies a CSS class called my-thumb to the thumb slot:

<SwitchUnstyled slotProps={{ thumb: { className: 'my-thumb' } }} />

Hook

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

The useSwitch hook lets you apply the functionality of a switch to a fully custom component. It returns props to be placed on the custom component, along with fields representing the component's internal state.

Hooks do not support slot props, but they do support customization props.

Basic example

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

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

Press Enter to start editing

Customized look and feel

<MUISwitch defaultChecked />

<MUISwitch defaultChecked />

Press Enter to start editing

Accessibility

To make the switch component accessible, you should ensure that the corresponding labels reflect the current state of the switch.

SwitchUnstyled API

Import

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

You can learn about the difference by reading this guide on minimizing bundle size.

Props

Props of the native component are also available.

Name	Type	Default	Description
checked	bool		If `true`, the component is checked.
component	elementType		The component used for the root node. Either a string to use a HTML element or a component.
defaultChecked	bool		The default checked state. Use when the component is not controlled.
disabled	bool		If `true`, the component is disabled.
onChange	func		Callback fired when the state is changed. Signature: `function(event: React.ChangeEvent<HTMLInputElement>) => void` event: The event source of the callback. You can pull out the new value by accessing `event.target.value` (string). You can pull out the new checked state by accessing `event.target.checked` (boolean).
readOnly	bool		If `true`, the component is read only.
required	bool		If `true`, the `input` element is required.
slotProps	{ input?: func \| object, root?: func \| object, thumb?: func \| object, track?: func \| object }	{}	The props used for each slot inside the Switch.
slots	{ input?: elementType, root?: elementType, thumb?: elementType, track?: elementType \| null }	{}	The components used for each slot inside the Switch. Either a string to use a HTML element or a component. See Slots API below for more details.

The ref is forwarded to the root element.

Slots

To learn how to customize the slot, check out the Overriding component structure guide.

Name	Default class	Default HTML tag	Description
root	.MuiSwitch-root	'span'	The component that renders the root.
input	.MuiSwitch-input	'input'	The component that renders the input.
thumb	.MuiSwitch-thumb	'span'	The component that renders the thumb.
track	.MuiSwitch-track	'span'	The component that renders the track.

You can override the style of the component using one of these customization options:

With a global class name.
With a rule name as part of the component's styleOverrides property in a custom theme.

CSS classes

These class names are useful for styling with CSS. They are applied to the root slot when specific states are triggered.

Global class	Description
.Mui-checked STATE	State class applied to the root element if the switch is checked
.Mui-disabled STATE	State class applied to the root element if the switch is disabled
.Mui-focusVisible STATE	State class applied to the root element if the switch has visible focus
.MuiSwitch-readOnly	Class applied to the root element if the switch is read-only

useSwitch API

Import

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

You can learn about the difference by reading this guide on minimizing bundle size.

Parameters

Name	Type	Description
checked	boolean	If `true`, the component is checked.
defaultChecked	boolean	The default checked state. Use when the component is not controlled.
disabled	boolean	If `true`, the component is disabled.
onBlur	React.FocusEventHandler
onChange	React.ChangeEventHandler<HTMLInputElement>	Callback fired when the state is changed.
onFocus	React.FocusEventHandler
onFocusVisible	React.FocusEventHandler
readOnly	boolean	If `true`, the component is read only.
required	boolean	If `true`, the `input` element is required.

Return value

Name	Type	Default	Description
checked	boolean		If `true`, the component will be checked.
disabled	boolean		If `true`, the component will be disabled.
focusVisible	boolean	false	If `true`, it indicates that the component is being focused using keyboard.
getInputProps	(externalProps?: React.HTMLAttributes<HTMLInputElement>) => UseSwitchInputSlotProps		Resolver for the input slot's props.
readOnly	boolean		If `true`, the component will be read only.