/chakra-ui-migrate
Migrate Chakra UI projects from v2 to v3, covering package changes, codemods, provider setup, color mode, prop renaming, compound components, theming, recipes, and Next.js updates. Use this skill whenever a user is upgrading Chakra UI versions, encountering breaking changes
$ npx -y skills add chakra-ui/chakra-ui --skill chakra-ui-migrate --agent claude-codeHow it fires
How this skill gets triggered: by you, by Claude, or both.
- Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
- You can call itInvoke it directly when you want it.
- Slash command
/chakra-ui-migrate
Context preview
The summary Claude sees to decide when to auto-load this skill.
Migrate Chakra UI projects from v2 to v3, covering package changes, codemods, provider setup, color mode, prop renaming, compound components, theming, recipes, and Next.js updates. Use this skill whenever a user is upgrading Chakra UI versions, encountering breaking changes
SKILL.md
chakra-ui-migrate.SKILL.mdname: chakra-ui-migrate
description: >
Migrate Chakra UI projects from v2 to v3, covering package changes, codemods,
provider setup, color mode, prop renaming, compound components, theming,
recipes, and Next.js updates. Use this skill whenever a user is upgrading
Chakra UI versions, encountering breaking changes after an upgrade, converting
old v2 patterns (ColorModeScript, useColorModeValue, styleConfig, extendTheme,
isDisabled, colorScheme, @chakra-ui/icons, framer-motion dependency), fixing
compound component patterns, or asking about differences between Chakra UI v2
and v3 — even if they don't say "migrate" or "upgrade" explicitly.
Chakra UI Migration: v2 → v3
You are guiding a developer through migrating their project from Chakra UI v2 to v3. Work through the steps below in order. Inspect the project first — never guess the package versions or framework.
> **Node requirement:** Chakra UI v3 requires Node >= 20.x. Confirm before > proceeding if the environment is uncertain.
---
Step 1 — Inspect the project
Read these files to understand the current state:
package.json
Look for:
- Current `@chakra-ui/react` version (v2.x vs v3.x)
- Related packages: `@chakra-ui/icons`, `@chakra-ui/hooks`,
`@chakra-ui/next-js`, `@emotion/styled`, `framer-motion`
- Framework: Next.js (App Router or Pages Router), Vite, plain React
- Package manager (from lockfiles: `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`,
`package-lock.json`)
Also spot-check key files when helpful:
- Provider / theme setup (`_app.tsx`, `layout.tsx`, `theme.ts`)
- Color mode usage (`ColorModeScript`, `useColorMode`, `useColorModeValue`)
- Any component files showing heavy v2 patterns
---
Step 2 — Update packages
Remove v2-only dependencies
# npm
npm uninstall @chakra-ui/icons @chakra-ui/hooks @chakra-ui/next-js @emotion/styled framer-motion
# pnpm
pnpm remove @chakra-ui/icons @chakra-ui/hooks @chakra-ui/next-js @emotion/styled framer-motion
# yarn
yarn remove @chakra-ui/icons @chakra-ui/hooks @chakra-ui/next-js @emotion/styled framer-motion
`@emotion/styled` and `framer-motion` are no longer required in v3.
Install v3 core packages
# npm
npm install @chakra-ui/react @emotion/react
# pnpm
pnpm add @chakra-ui/react @emotion/react
# yarn
yarn add @chakra-ui/react @emotion/react
Replacements for removed packages
| Removed | Replacement | | -------------------- | -------------------------------------------- | | `@chakra-ui/icons` | `lucide-react` or `react-icons` | | `@chakra-ui/hooks` | `react-use` or `usehooks-ts` | | `@chakra-ui/next-js` | `asChild` prop pattern (see Next.js section) |
---
Step 3 — Run the codemod
The official codemod handles most mechanical changes: component renames, prop updates, import rewrites, and compound component restructuring. It does not replace manual review — plan to audit the output.
**Dry run first (no files changed):**
npx @chakra-ui/codemod upgrade --dry
Review what it proposes. When satisfied:
npx @chakra-ui/codemod upgrade
After the codemod, commit the changes before making manual edits so you have a clean diff to work from.
---
Step 4 — Update the Provider
Old v2 pattern
// v2
import { ChakraProvider } from "@chakra-ui/react"
import theme from "./theme"
;<ChakraProvider theme={theme}>{children}</ChakraProvider>New v3 pattern (using Chakra CLI snippets)
Generate the provider and component snippets:
npx @chakra-ui/cli snippet add
This creates `components/ui/provider.tsx` (plus `toaster` and `tooltip` snippets) and automatically installs required npm dependencies — including `next-themes`. Import and use it:
// v3 — app/layout.tsx (Next.js App Router)
import { Provider } from "@/components/ui/provider"
;<html lang="en" suppressHydrationWarning>
<body>
<Provider>{children}</Provider>
</body>
</html>The `Provider` file includes `"use client"` — do not add it to `layout.tsx`. See the Next.js section for Pages Router placement.
Custom theme in v3
Replace `extendTheme` with `createSystem`:
// v2
import { extendTheme } from "@chakra-ui/react"
// v3
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"
export const theme = extendTheme({ colors: { brand: { 500: "#2196f3" } } })
const config = defineConfig({
theme: { tokens: { colors: { brand: { 500: { value: "#2196f3" } } } } },
})
export const system = createSystem(defaultConfig, config)Pass `system` to `ChakraProvider` via `value={system}`.
---
Step 5 — Color mode migration
Remove all v2 color mode patterns
// REMOVE these v2 imports and usages:
import { ColorModeScript } from "@chakra-ui/react"
// ❌
import { useColorMode } from "@chakra-ui/react"
// ❌ (use next-themes)
import { useColorModeValue } from "@chakra-ui/react"
// ❌ (use CSS tokens)
import { DarkMode, LightMode } from "@chakra-ui/react"
// ❌
// Also remove from _document.tsx:
;<ColorModeScript initialColorMode={theme.config.initialColorMode} /> // ❌v3 color mode approach
Color mode is handled by `next-themes` via the generated `Provider`. Use semantic tokens that automatically respond to the active color mode:
// Use Chakra semantic tokens — they flip automatically in dark mode
<Box color="fg.default" bg="bg.subtle">
...
</Box>
For a color mode toggle, use the generated `components/ui/color-mode.tsx` snippet or `useColorMode` from `next-themes` directly.
---
Step 6 — Prop renames
These boolean and style props were renamed in v3 for consistency with HTML and modern React conventions. The codemod catches most of these, but verify manually afterward.
Boolean props
| v2 | v3 | | ----------------- | --------------- | | `isOpen` | `open` | | `defaultIsOpen` | `defaultOpen` |
Read more
name: chakra-ui-migrate description: > Migrate Chakra UI projects from v2 to v3, covering package changes, codemods, provider setup, color mode, prop renaming, compound components, theming, recipes, and Next.js updates. Use this skill whenever a user is upgrading Chakra UI versions, encountering breaking changes after an upgrade, converting old v2 patterns (ColorModeScript, useColorModeValue, styleConfig, extendTheme, isDisabled, colorScheme, @chakra-ui/icons, framer-motion dependency), fixing compound component patterns, or asking about differences between Chakra UI v2 and v3 — even if they don't say "migrate" or "upgrade" explicitly.
Chakra UI Migration: v2 → v3
You are guiding a developer through migrating their project from Chakra UI v2 to v3. Work through the steps below in order. Inspect the project first — never guess the package versions or framework.
> **Node requirement:** Chakra UI v3 requires Node >= 20.x. Confirm before > proceeding if the environment is uncertain.
---
Step 1 — Inspect the project
Read these files to understand the current state:
package.json
Look for:
- Current `@chakra-ui/react` version (v2.x vs v3.x)
- Related packages: `@chakra-ui/icons`, `@chakra-ui/hooks`,
`@chakra-ui/next-js`, `@emotion/styled`, `framer-motion`
- Framework: Next.js (App Router or Pages Router), Vite, plain React
- Package manager (from lockfiles: `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`,
`package-lock.json`)
Also spot-check key files when helpful:
- Provider / theme setup (`_app.tsx`, `layout.tsx`, `theme.ts`)
- Color mode usage (`ColorModeScript`, `useColorMode`, `useColorModeValue`)
- Any component files showing heavy v2 patterns
---
Step 2 — Update packages
Remove v2-only dependencies
# npm npm uninstall @chakra-ui/icons @chakra-ui/hooks @chakra-ui/next-js @emotion/styled framer-motion # pnpm pnpm remove @chakra-ui/icons @chakra-ui/hooks @chakra-ui/next-js @emotion/styled framer-motion # yarn yarn remove @chakra-ui/icons @chakra-ui/hooks @chakra-ui/next-js @emotion/styled framer-motion
`@emotion/styled` and `framer-motion` are no longer required in v3.
Install v3 core packages
# npm npm install @chakra-ui/react @emotion/react # pnpm pnpm add @chakra-ui/react @emotion/react # yarn yarn add @chakra-ui/react @emotion/react
Replacements for removed packages
| Removed | Replacement | | -------------------- | -------------------------------------------- | | `@chakra-ui/icons` | `lucide-react` or `react-icons` | | `@chakra-ui/hooks` | `react-use` or `usehooks-ts` | | `@chakra-ui/next-js` | `asChild` prop pattern (see Next.js section) |
---
Step 3 — Run the codemod
The official codemod handles most mechanical changes: component renames, prop updates, import rewrites, and compound component restructuring. It does not replace manual review — plan to audit the output.
**Dry run first (no files changed):**
npx @chakra-ui/codemod upgrade --dry
Review what it proposes. When satisfied:
npx @chakra-ui/codemod upgrade
After the codemod, commit the changes before making manual edits so you have a clean diff to work from.
---
Step 4 — Update the Provider
Old v2 pattern
// v2
import { ChakraProvider } from "@chakra-ui/react"
import theme from "./theme"
;<ChakraProvider theme={theme}>{children}</ChakraProvider>New v3 pattern (using Chakra CLI snippets)
Generate the provider and component snippets:
npx @chakra-ui/cli snippet add
This creates `components/ui/provider.tsx` (plus `toaster` and `tooltip` snippets) and automatically installs required npm dependencies — including `next-themes`. Import and use it:
// v3 — app/layout.tsx (Next.js App Router)
import { Provider } from "@/components/ui/provider"
;<html lang="en" suppressHydrationWarning>
<body>
<Provider>{children}</Provider>
</body>
</html>The `Provider` file includes `"use client"` — do not add it to `layout.tsx`. See the Next.js section for Pages Router placement.
Custom theme in v3
Replace `extendTheme` with `createSystem`:
// v2
import { extendTheme } from "@chakra-ui/react"
// v3
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"
export const theme = extendTheme({ colors: { brand: { 500: "#2196f3" } } })
const config = defineConfig({
theme: { tokens: { colors: { brand: { 500: { value: "#2196f3" } } } } },
})
export const system = createSystem(defaultConfig, config)Pass `system` to `ChakraProvider` via `value={system}`.
---
Step 5 — Color mode migration
Remove all v2 color mode patterns
// REMOVE these v2 imports and usages:
import { ColorModeScript } from "@chakra-ui/react"
// ❌
import { useColorMode } from "@chakra-ui/react"
// ❌ (use next-themes)
import { useColorModeValue } from "@chakra-ui/react"
// ❌ (use CSS tokens)
import { DarkMode, LightMode } from "@chakra-ui/react"
// ❌
// Also remove from _document.tsx:
;<ColorModeScript initialColorMode={theme.config.initialColorMode} /> // ❌v3 color mode approach
Color mode is handled by `next-themes` via the generated `Provider`. Use semantic tokens that automatically respond to the active color mode:
// Use Chakra semantic tokens — they flip automatically in dark mode <Box color="fg.default" bg="bg.subtle"> ... </Box>
For a color mode toggle, use the generated `components/ui/color-mode.tsx` snippet or `useColorMode` from `next-themes` directly.
---
Step 6 — Prop renames
These boolean and style props were renamed in v3 for consistency with HTML and modern React conventions. The codemod catches most of these, but verify manually afterward.
Boolean props
| v2 | v3 | | ----------------- | --------------- | | `isOpen` | `open` | | `defaultIsOpen` | `defaultOpen` |
Chakra UI is a component system for building SaaS products with speed ⚡️
Repo: chakra-ui/chakra-ui
Other skills on chakra-ui.
- /chakra-ui-builder
Build responsive, accessible UI components and layouts using Chakra UI v3, install or configure Chakra UI in new and existing projects, and design scalable themes using tokens, semantic tokens, recipes, and slot recipes. Use this skill whenever a user asks to build, create, or
Open skill - /chakra-ui-refactor
Review, convert, and improve UI code using Chakra UI v3. Use this skill whenever a user wants to review Chakra UI code for issues, convert plain HTML/CSS, Tailwind, CSS Modules, or styled-components to Chakra UI, clean up messy Chakra components, fix layout structure or token
Open skill