Switch

Refer to the v3 Switch documentation for complete API reference, styling guide, and advanced examples. This guide only focuses on migrating from HeroUI v2.

Structure Changes

In v2, Switch used a simple structure with children as label:

import { Switch } from "@heroui/react";

export default function App() {
  return <Switch>Enable notifications</Switch>;
}

In v3, Switch requires compound components:

import { Switch, Label } from "@heroui/react";

export default function App() {
  return (
    <Switch>
      <Switch.Content>
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        Enable notifications
      </Switch.Content>
    </Switch>
  );
}

Key Changes

1. Component Structure

v2: Simple Switch with children as label v3: Compound components (Switch.Content, Switch.Control, Switch.Thumb) with Label component

2. Prop Changes

v2 Prop	v3 Location	Notes
`onValueChange`	`onChange`	Renamed event handler
`size`	`size`	Still exists on root (`sm` \| `md` \| `lg`)
`label`	—	Use `Label` component
`color`	—	Removed (use Tailwind CSS)
`thumbIcon`	—	Use `Switch.Icon` inside `Switch.Thumb`
`startContent`	—	Customize control directly
`endContent`	—	Customize control directly
`classNames`	—	Use `className` props on individual components
`disableAnimation`	—	Removed (animations handled differently)

3. New Components

SwitchGroup - For grouping multiple switches
Switch.Content - The clickable label wrapping the control and Label
Switch.Icon - For icons inside the thumb

Migration Examples

Controlled Switch

v2

```tsx
import { useState } from "react";

const [isSelected, setIsSelected] = useState(true);

<Switch isSelected={isSelected} onValueChange={setIsSelected}>
  Airplane mode
</Switch>
```

v3

```tsx
import { useState } from "react";

const [isSelected, setIsSelected] = useState(true);

<Switch isSelected={isSelected} onChange={setIsSelected}>
  <Switch.Content>
    <Switch.Control>
      <Switch.Thumb />
    </Switch.Control>
    Airplane mode
  </Switch.Content>
</Switch>
```

Without Label

v2

```tsx
<Switch defaultSelected aria-label="Automatic updates" />
```

v3

```tsx
<Switch defaultSelected aria-label="Automatic updates">
  <Switch.Content>
    <Switch.Control>
      <Switch.Thumb />
    </Switch.Control>
  </Switch.Content>
</Switch>
```

With Thumb Icon

v2

```tsx
<Switch thumbIcon={<CheckIcon />}>Enable notifications</Switch>
```

v3

```tsx
<Switch>
  <Switch.Content>
    <Switch.Control>
      <Switch.Thumb>
        <Switch.Icon>
          <CheckIcon />
        </Switch.Icon>
      </Switch.Thumb>
    </Switch.Control>
    Enable notifications
  </Switch.Content>
</Switch>
```

With Start/End Content

v2

```tsx
<Switch
  startContent={<SunIcon />}
  endContent={<MoonIcon />}
>
  Dark mode
</Switch>
```

v3

```tsx
<Switch>
  <Switch.Content>
    <Switch.Control className="flex items-center gap-2">
      <SunIcon />
      <Switch.Thumb />
      <MoonIcon />
    </Switch.Control>
    Dark mode
  </Switch.Content>
</Switch>
```

With Label and Description

v2

```tsx
<Switch description="You will receive notifications for all activity">
  Enable notifications
</Switch>
```

v3

```tsx
import { Switch, Label, Description } from "@heroui/react";

<Switch>
  <Switch.Content>
    <Switch.Control>
      <Switch.Thumb />
    </Switch.Control>
    Enable notifications
  </Switch.Content>
  <Description>You will receive notifications for all activity</Description>
</Switch>
```

Sizes and Colors

v2

```tsx
{/* Sizes */}
<div className="flex gap-4">
  <Switch size="sm">Small</Switch>
  <Switch size="md">Medium</Switch>
  <Switch size="lg">Large</Switch>
</div>

{/* Colors */}
<Switch color="primary">Primary</Switch>
<Switch color="success">Success</Switch>
<Switch color="danger">Danger</Switch>
```

v3

```tsx
{/* Sizes */}
<div className="flex gap-4">
  <Switch size="sm">
    <Switch.Content>
      <Switch.Control>
        <Switch.Thumb />
      </Switch.Control>
      Small
    </Switch.Content>
  </Switch>
  <Switch size="md">
    <Switch.Content>
      <Switch.Control>
        <Switch.Thumb />
      </Switch.Control>
      Medium
    </Switch.Content>
  </Switch>
  <Switch size="lg">
    <Switch.Content>
      <Switch.Control>
        <Switch.Thumb />
      </Switch.Control>
      Large
    </Switch.Content>
  </Switch>
</div>

{/* Colors - Use Tailwind CSS classes */}
<Switch>
  <Switch.Content>
    <Switch.Control className="data-[selected=true]:bg-accent">
      <Switch.Thumb />
    </Switch.Control>
    Primary
  </Switch.Content>
</Switch>
<Switch>
  <Switch.Content>
    <Switch.Control className="data-[selected=true]:bg-success">
      <Switch.Thumb />
    </Switch.Control>
    Success
  </Switch.Content>
</Switch>
<Switch>
  <Switch.Content>
    <Switch.Control className="data-[selected=true]:bg-danger">
      <Switch.Thumb />
    </Switch.Control>
    Danger
  </Switch.Content>
</Switch>
```

Switch Group

v2

```tsx
{/* No built-in group component in v2 */}
<div className="flex flex-col gap-2">
  <Switch name="notifications">Allow Notifications</Switch>
  <Switch name="marketing">Marketing emails</Switch>
</div>
```

v3

```tsx
import { SwitchGroup } from "@heroui/react";

<SwitchGroup>
  <Switch name="notifications">
    <Switch.Content>
      <Switch.Control>
        <Switch.Thumb />
      </Switch.Control>
      Allow Notifications
    </Switch.Content>
  </Switch>
  <Switch name="marketing">
    <Switch.Content>
      <Switch.Control>
        <Switch.Thumb />
      </Switch.Control>
      Marketing emails
    </Switch.Content>
  </Switch>
</SwitchGroup>
```

Component Anatomy

The v3 Switch follows this structure:

Switch (Root)
  ├── Switch.Content (the clickable label)
  │   ├── Switch.Control
  │   │   └── Switch.Thumb
  │   │       └── Switch.Icon (optional)
  │   └── Label
  ├── Description (optional, sibling)
  └── FieldError (optional, sibling)

For groups:

SwitchGroup
  ├── Switch
  │   ├── Switch.Content
  │   │   ├── Switch.Control
  │   │   │   └── Switch.Thumb
  │   │   └── Label
  │   └── Description (optional)
  └── Switch
      ├── Switch.Content
      │   ├── Switch.Control
      │   │   └── Switch.Thumb
      │   └── Label
      └── Description (optional)

Important Notes

Event Handler

v2: onValueChange prop
v3: onChange prop (same signature: (isSelected: boolean) => void)

Label Handling

v2: Children were used as label
v3: Label goes inside Switch.Content (the clickable label); Description/FieldError are siblings of Switch.Content

Icons

v2: thumbIcon prop for icon inside thumb, startContent/endContent for icons outside
v3: Use Switch.Icon inside Switch.Thumb for thumb icon, customize Switch.Control for start/end content

Summary

Component Structure: Must use compound components (Switch.Content, Switch.Control, Switch.Thumb)
Clickable Label: Use Switch.Content to wrap Switch.Control and Label; place Description/FieldError as siblings of Switch.Content
Label Handling: Children no longer used as label - use Label component inside Switch.Content
Event Handler: onValueChange → onChange
Styling Props Removed: color - use Tailwind CSS
Icon Props Removed: thumbIcon, startContent, endContent - use components or customize directly
ClassNames Removed: Use className props on individual components
New Components: SwitchGroup for grouping switches, Switch.Content as the clickable label wrapping the control and Label