Switch (Toggle)

Switches are a pleasant interface for toggling a value between two states, and offer the same semantics and keyboard navigation as native checkbox elements.

To get started, install Headless UI via npm or yarn:

# npm npm install @headlessui/react # Yarn yarn add @headlessui/react

Switches are built using the Switch component. You can toggle your Switch by clicking directly on the component, or by pressing the spacebar while its focused.

Toggling the switch calls the onChange function with a negated version of the checked value.

import { useState } from 'react' import { Switch } from '@headlessui/react' function MyToggle() { const [enabled, setEnabled] = useState(false) return ( <Switch checked={enabled} onChange={setEnabled} className={`${ enabled ? 'bg-blue-600' : 'bg-gray-200' } relative inline-flex items-center h-6 rounded-full w-11`} > <span className="sr-only">Enable notifications</span> <span className={`${ enabled ? 'translate-x-6' : 'translate-x-1' } inline-block w-4 h-4 transform bg-white rounded-full`} /> </Switch> ) }

By default, a Switch renders a button as well as whatever children you pass into it. This can make it harder to implement certain UIs, since the children will be nested within the button.

In these situations, you can use the Switch.Label component for more flexibility.

This example demonstrates how to use the Switch.Group, Switch and Switch.Label components to render a label as a sibling to the button. Note that Switch.Label works alongside a Switch component, and they both must be rendered within a parent Switch.Group component.

import { useState } from 'react' import { Switch } from '@headlessui/react' export default function CustomLabelExample() { const [enabled, setEnabled] = useState(false) return (
<Switch.Group>
<div className="flex items-center">
<Switch.Label className="mr-4">Enable notifications</Switch.Label>
<Switch checked={enabled} onChange={setEnabled} className={`${ enabled ? 'bg-blue-600' : 'bg-gray-200' } relative inline-flex items-center h-6 rounded-full w-11 transition-colors focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500`} > <span className={`${ enabled ? 'translate-x-6' : 'translate-x-1' } inline-block w-4 h-4 transform bg-white rounded-full transition-transform`} /> </Switch> </div>
</Switch.Group>
) }

By default, clicking a Switch.Label will toggle the Switch, just like labels in native HTML checkboxes do. If you'd like to make the label non-clickable (which you might if it doesn't make sense for your design), you can add a passive prop to the Switch.Label component:

import { useState } from 'react' import { Switch } from '@headlessui/react' export default function CustomLabelExample() { const [enabled, setEnabled] = useState(false) return ( <Switch.Group>
<Switch.Label passive>Enable notifications</Switch.Label>
<Switch checked={enabled} onChange={setEnabled}> {/* ... */} </Switch> </Switch.Group> ) }

Because Switches are typically always rendered to the DOM (rather than being mounted/unmounted like other components), simple CSS transitions are often enough to animate your Switch:

import { useState } from "react"; import { Switch } from "@headlessui/react"; export default function Example() { const [enabled, setEnabled] = useState(false); return ( <Switch checked={enabled} onChange={setEnabled}> <span /* Transition the Switch's knob on state change */
className={`transform transition ease-in-out duration-200
${enabled ? "translate-x-9" : "translate-x-0"}
`}
/> {/* ... */} </Switch> ); }

Because they're renderless, Headless UI components also compose well with other animation libraries in the React ecosystem like Framer Motion and React Spring.

By default, the children of a Switch will be used as the label for screen readers. If you're using Switch.Label, the content of your Switch component will be ignored by assistive technologies.

Clicking a Switch or a Switch.Label toggles the Switch on and off.

CommandDescription

Space when a Switch is focused

Toggles the Switch

All relevant ARIA attributes are automatically managed.

The main Switch component.

PropDefaultDescription
asbutton
String | Component

The element or component the Switch should render as.

checked
Boolean

Whether or not the switch is checked.

onChange
(value: Boolean) => void

The function to call when the switch is toggled.

Render PropDescription
checked

Boolean

Whether or not the switch is checked.

PropDefaultDescription
aslabel
String | Component

The element or component the Switch.Label should render as.

passivefalse
Boolean

When true, clicking the label won't toggle the Switch.

PropDefaultDescription
asp
String | Component

The element or component the Switch.Description should render as.

PropDefaultDescription
asFragment
String | Component

The element or component the Switch.Group should render as.

If you're interested in predesigned component examples using Headless UI and Tailwind CSS, check out Tailwind UI — a collection of beautifully designed and expertly crafted components built by us.

It's a great way to support our work on open-source projects like this and makes it possible for us to improve them and keep them well-maintained.