> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/mui/base-ui/llms.txt
> Use this file to discover all available pages before exploring further.

# Switch

> A toggle switch for binary on/off states.

A toggle switch for binary on/off states.

## Import

```jsx theme={null}
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

```jsx theme={null}
<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.

```jsx theme={null}
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.

```jsx theme={null}
<Switch.Root defaultChecked>
  <Switch.Thumb />
</Switch.Root>
```

### onCheckedChange

**Type:** `(checked: boolean, eventDetails: ChangeEventDetails) => void`

Event handler called when the switch is activated or deactivated.

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

### disabled

**Type:** `boolean`

**Default:** `false`

Whether the component should ignore user interaction.

```jsx theme={null}
<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

<Tabs items={['Tailwind CSS', 'CSS Modules']}>
  <Tab value="Tailwind CSS">
    ```jsx theme={null}
    <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>
    ```
  </Tab>

  <Tab value="CSS Modules">
    ```jsx theme={null}
    <Switch.Root className={styles.root}>
      <Switch.Thumb className={styles.thumb} />
    </Switch.Root>
    ```

    ```css theme={null}
    .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);
    }
    ```
  </Tab>
</Tabs>

## Common Patterns

### With Label

```jsx theme={null}
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

```jsx theme={null}
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

```jsx theme={null}
<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

```jsx theme={null}
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

```jsx theme={null}
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>
  );
}
```