headlessui/packages/@headlessui-react/src/components/switch/README.md

Switch (Toggle)

View live demo on CodeSandbox

The Switch component and related child components are used to quickly build custom switch/toggle components that are fully accessible out of the box, including correct ARIA attribute management and robust keyboard support.

• Installation
• Basic example
• Using a custom label
• Component API

Installation

# npm
npm install @headlessui/react

# Yarn
yarn add @headlessui/react

Basic example

Switches are built using the Switch component. Optionally you can also use the Switch.Group and Switch.Label components.

import { useState } from 'react'
import { Switch } from '@headlessui/react'

function NotificationsToggle() {
  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>
  )
}

Using a custom label

By default the Switch will use the contents as the label for screenreaders. If you need more control, you can render a Switch.Label outside of the Switch, as long as both the switch and label are within a parent Switch.Group.

Clicking the label will toggle the switch state, like you'd expect from a native checkbox.

import { useState } from 'react'
import { Switch } from '@headlessui/react'

function NotificationsToggle() {
  const [enabled, setEnabled] = useState(false)

  return (
    <Switch.Group>
      <Switch.Label>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`}
      >
        <span
          className={`${
            enabled ? 'translate-x-6' : 'translate-x-1'
          } inline-block w-4 h-4 transform bg-white rounded-full`}
        />
      </Switch>
    </Switch.Group>
  )
}

Component API

Switch

<Switch checked={checkedState} onChange={setCheckedState}>
  <span className="sr-only">Enable notifications</span>
  {/* ... */}
</Switch>

Props

Prop	Type	Default	Description
as	String | Component	button	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 prop object

Prop	Type	Description
checked	Boolean	Whether or not the switch is checked.

Switch.Label

<Switch.Group>
  <Switch.Label>Enable notifications</Switch.Label>
  <Switch checked={enabled} onChange={setEnabled} className="...">
    {/* ... */}
  </Switch>
</Switch.Group>

Props

Prop	Type	Default	Description
as	String | Component	label	The element or component the Switch.Label should render as.
passive	Boolean	false	When passive is false, clicking the Switch.Label will not toggle the Switch.

Switch.Description

<Switch.Group>
  <Switch.Description>Enable notifications</Switch.Description>
  <Switch checked={enabled} onChange={setEnabled} className="...">
    {/* ... */}
  </Switch>
</Switch.Group>

Props

Prop	Type	Default	Description
as	String | Component	label	The element or component the Switch.Description should render as.

Switch.Group

<Switch.Group>
  <Switch.Label>Enable notifications</Switch.Label>
  <Switch checked={enabled} onChange={setEnabled} className="...">
    {/* ... */}
  </Switch>
</Switch.Group>

Props

Prop	Type	Default	Description
as	String | Component	React.Fragment (no wrapper element)	The element or component the Switch.Group should render as.