Switch

A toggle switch for binary on/off states.

Import

import { Switch } from '@base-ui/react/switch';

Anatomy

The Switch component consists of two parts:

Switch.Root - The switch control itself
Switch.Thumb - The draggable thumb element

Basic Usage

<Switch.Root>
  <Switch.Thumb />
</Switch.Root>

Key Features

Controlled and uncontrolled modes
Accessible with proper ARIA attributes
Works seamlessly with Field and Form components
Custom render props
Support for read-only and disabled states

Key Props

checked

Type: boolean Whether the switch is currently active. Use with onCheckedChange for controlled mode.

const [checked, setChecked] = React.useState(false);

<Switch.Root checked={checked} onCheckedChange={setChecked}>
  <Switch.Thumb />
</Switch.Root>

defaultChecked

Type: boolean Default: false Whether the switch is initially active. Use for uncontrolled mode.

<Switch.Root defaultChecked>
  <Switch.Thumb />
</Switch.Root>

onCheckedChange

Type: (checked: boolean, eventDetails: ChangeEventDetails) => void Event handler called when the switch is activated or deactivated.

<Switch.Root onCheckedChange={(checked) => console.log('Switch:', checked)}>
  <Switch.Thumb />
</Switch.Root>

disabled

Type: boolean Default: false Whether the component should ignore user interaction.

<Switch.Root disabled>
  <Switch.Thumb />
</Switch.Root>

readOnly

Type: boolean Default: false Whether the user should be unable to activate or deactivate the switch.

required

Type: boolean Default: false Whether the user must activate the switch before submitting a form.

name

Type: string Identifies the field when a form is submitted.

value

Type: string The value submitted with the form when the switch is on.

uncheckedValue

Type: string The value submitted with the form when the switch is off.

inputRef

Type: React.Ref<HTMLInputElement> A ref to access the hidden input element.

Styling

Tab Title
Tab Title

<Switch.Root className="relative w-11 h-6 rounded-full bg-gray-200 data-[checked]:bg-blue-500 transition-colors">
  <Switch.Thumb className="absolute left-0.5 top-0.5 w-5 h-5 rounded-full bg-white shadow-md transition-transform data-[checked]:translate-x-5" />
</Switch.Root>

<Switch.Root className={styles.root}>
  <Switch.Thumb className={styles.thumb} />
</Switch.Root>

.root {
  position: relative;
  width: 2.75rem;
  height: 1.5rem;
  border-radius: 9999px;
  background-color: #e5e7eb;
  transition: background-color 0.2s;
}

.root[data-checked] {
  background-color: #3b82f6;
}

.root[data-disabled] {
  opacity: 0.5;
  cursor: not-allowed;
}

.thumb {
  position: absolute;
  left: 0.125rem;
  top: 0.125rem;
  width: 1.25rem;
  height: 1.25rem;
  border-radius: 50%;
  background-color: white;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
  transition: transform 0.2s;
}

.thumb[data-checked] {
  transform: translateX(1.25rem);
}

Common Patterns

With Label

import { Field } from '@base-ui/react/switch';

<Field.Root>
  <div className="flex items-center justify-between">
    <Field.Label>Enable notifications</Field.Label>
    <Switch.Root name="notifications">
      <Switch.Thumb />
    </Switch.Root>
  </div>
</Field.Root>

Settings List

function SettingsList() {
  const [settings, setSettings] = React.useState({
    notifications: true,
    darkMode: false,
    analytics: true,
  });

  return (
    <div className="space-y-4">
      <div className="flex items-center justify-between">
        <div>
          <div className="font-medium">Push Notifications</div>
          <div className="text-sm text-gray-500">Receive push notifications</div>
        </div>
        <Switch.Root
          checked={settings.notifications}
          onCheckedChange={(checked) =>
            setSettings({ ...settings, notifications: checked })
          }
        >
          <Switch.Thumb />
        </Switch.Root>
      </div>
      
      <div className="flex items-center justify-between">
        <div>
          <div className="font-medium">Dark Mode</div>
          <div className="text-sm text-gray-500">Use dark theme</div>
        </div>
        <Switch.Root
          checked={settings.darkMode}
          onCheckedChange={(checked) =>
            setSettings({ ...settings, darkMode: checked })
          }
        >
          <Switch.Thumb />
        </Switch.Root>
      </div>
    </div>
  );
}

With Icons

<Switch.Root className="relative w-14 h-7 rounded-full bg-gray-200 data-[checked]:bg-blue-500">
  <Switch.Thumb className="absolute left-1 top-1 w-5 h-5 rounded-full bg-white flex items-center justify-center transition-transform data-[checked]:translate-x-7">
    <svg className="w-3 h-3" fill="currentColor">
      <path d="M12 2.25a.75.75 0 01.75.75v2.25a.75.75 0 01-1.5 0V3a.75.75 0 01.75-.75zM7.5 12a4.5 4.5 0 119 0 4.5 4.5 0 01-9 0z" />
    </svg>
  </Switch.Thumb>
</Switch.Root>

Form Integration

import { Form, Field } from '@base-ui/react/switch';

<Form.Root>
  <Field.Root name="terms" required>
    <div className="flex items-center gap-3">
      <Switch.Root>
        <Switch.Thumb />
      </Switch.Root>
      <Field.Label>
        I agree to the terms and conditions
      </Field.Label>
    </div>
    <Field.Error />
  </Field.Root>
</Form.Root>

Color Variants

function ColoredSwitch() {
  const [checked, setChecked] = React.useState(false);

  return (
    <Switch.Root
      checked={checked}
      onCheckedChange={setChecked}
      className="relative w-11 h-6 rounded-full bg-gray-200 data-[checked]:bg-green-500"
    >
      <Switch.Thumb className="absolute left-0.5 top-0.5 w-5 h-5 rounded-full bg-white shadow transition-transform data-[checked]:translate-x-5" />
    </Switch.Root>
  );
}

Getting Started

Handbook

Inputs

Data Display

Navigation

Overlays

Forms

Layout

Utilities

Import

Anatomy

Basic Usage

Key Features

Key Props

checked

defaultChecked

onCheckedChange

disabled

readOnly

required

name

value

uncheckedValue

inputRef

Styling

Common Patterns

With Label

Settings List

With Icons

Form Integration

Color Variants

​Import

​Anatomy

​Basic Usage

​Key Features

​Key Props

​checked

​defaultChecked

​onCheckedChange

​disabled

​readOnly

​required

​name

​value

​uncheckedValue

​inputRef

​Styling

​Common Patterns

​With Label

​Settings List

​With Icons

​Form Integration

​Color Variants

Import

Anatomy

Basic Usage

Key Features

Key Props

checked

defaultChecked

onCheckedChange

disabled

readOnly

required

name

value

uncheckedValue

inputRef

Styling

Common Patterns

With Label

Settings List

With Icons

Form Integration

Color Variants