# Switch **Category**: react **URL**: https://heroui.com/en/docs/react/migration/switch **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/migration/(components)/switch.mdx > Migration guide for Switch from HeroUI v2 to v3 *** Refer to the [v3 Switch documentation](/docs/react/components/switch) 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: ```tsx import { Switch } from "@heroui/react"; export default function App() { return Enable notifications; } ``` In v3, Switch requires compound components: ```tsx import { Switch, Label } from "@heroui/react"; export default function App() { return ( Enable notifications ); } ``` ## 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 ```tsx import { useState } from "react"; const [isSelected, setIsSelected] = useState(true); Airplane mode ``` ```tsx import { useState } from "react"; const [isSelected, setIsSelected] = useState(true); Airplane mode ``` ### Without Label ```tsx ``` ```tsx ``` ### With Thumb Icon ```tsx }>Enable notifications ``` ```tsx Enable notifications ``` ### With Start/End Content ```tsx } endContent={} > Dark mode ``` ```tsx Dark mode ``` ### With Label and Description ```tsx Enable notifications ``` ```tsx import { Switch, Label, Description } from "@heroui/react"; Enable notifications You will receive notifications for all activity ``` ### Sizes and Colors ```tsx {/* Sizes */}

Small Medium Large

{/* Colors */} Primary Success Danger ``` ```tsx {/* Sizes */}

Small Medium Large

{/* Colors - Use Tailwind CSS classes */} Primary Success Danger ``` ### Switch Group ```tsx {/* No built-in group component in v2 */}

Allow Notifications Marketing emails

``` ```tsx import { SwitchGroup } from "@heroui/react"; Allow Notifications Marketing emails ``` ## 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 1. **Component Structure**: Must use compound components (`Switch.Content`, `Switch.Control`, `Switch.Thumb`) 2. **Clickable Label**: Use `Switch.Content` to wrap `Switch.Control` and `Label`; place `Description`/`FieldError` as siblings of `Switch.Content` 3. **Label Handling**: Children no longer used as label - use `Label` component inside `Switch.Content` 4. **Event Handler**: `onValueChange` → `onChange` 5. **Styling Props Removed**: `color` - use Tailwind CSS 6. **Icon Props Removed**: `thumbIcon`, `startContent`, `endContent` - use components or customize directly 7. **ClassNames Removed**: Use `className` props on individual components 8. **New Components**: `SwitchGroup` for grouping switches, `Switch.Content` as the clickable label wrapping the control and `Label`