# Switch **Category**: react **URL**: https://www.heroui.com/docs/react/migration/switch **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/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 ( ); } ``` ## Key Changes ### 1. Component Structure **v2:** Simple Switch with children as label **v3:** Compound components (`Switch.Control`, `Switch.Thumb`, `Switch.Content`) 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` - Container for label and description - `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); ``` ### Without Label ```tsx ``` ```tsx ``` ### With Thumb Icon ```tsx }>Enable notifications ``` ```tsx ``` ### With Start/End Content ```tsx } endContent={} > Dark mode ``` ```tsx ``` ### With Label and Description ```tsx Enable notifications ``` ```tsx import { Switch, Label, Description } from "@heroui/react"; You will receive notifications for all activity ``` ### Sizes and Colors ```tsx {/* Sizes */}
Small Medium Large
{/* Colors */} Primary Success Danger ``` ```tsx {/* Sizes */}
{/* Colors - Use Tailwind CSS classes */} ``` ### Switch Group ```tsx {/* No built-in group component in v2 */}
Allow Notifications Marketing emails
``` ```tsx import { SwitchGroup } from "@heroui/react"; ``` ## Component Anatomy The v3 Switch follows this structure: ``` Switch (Root) ├── Switch.Control │ └── Switch.Thumb │ └── Switch.Icon (optional) └── Switch.Content (optional) ├── Label (optional) └── Description (optional) ``` For groups: ``` SwitchGroup ├── Switch │ ├── Switch.Control │ │ └── Switch.Thumb │ └── Switch.Content │ ├── Label │ └── Description (optional) └── Switch ├── Switch.Control │ └── Switch.Thumb └── Switch.Content ├── 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:** Use `Label` component inside `Switch.Content`; optionally add `Description` alongside it ### 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.Control`, `Switch.Thumb`, `Switch.Content`) 2. **Content Container**: Use `Switch.Content` to wrap `Label` and `Description` for proper layout 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` for label/description container