Terminal
Terminal/Skill
Walks a developer through upgrading a Chakra UI project from v2 to v3, including packages, codemods and breaking prop changes.
By Chakra UI
Works with
npx skills add chakra-ui/chakra-ui --skill chakra-ui-migrateYou 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.
Read these files to understand the current state:
package.json
Look for:
@chakra-ui/react version (v2.x vs v3.x)@chakra-ui/icons, @chakra-ui/hooks,
@chakra-ui/next-js, @emotion/styled, framer-motionpnpm-lock.yaml, yarn.lock, bun.lock,
package-lock.json)Also spot-check key files when helpful:
_app.tsx, layout.tsx, theme.ts)ColorModeScript, useColorMode, useColorModeValue)# 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.
# npm
npm install @chakra-ui/react @emotion/react
# pnpm
pnpm add @chakra-ui/react @emotion/react
# yarn
yarn add @chakra-ui/react @emotion/react
| 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) |
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.
// v2
import { ChakraProvider } from "@chakra-ui/react"
import theme from "./theme"
;<ChakraProvider theme={theme}>{children}</ChakraProvider>
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.
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}.
// 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} /> // ❌
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.
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.
| v2 | v3 |
|---|---|
isOpen | open |
defaultIsOpen | defaultOpen |
isDisabled | disabled |
isInvalid | invalid |
isRequired | required |
isReadOnly | readOnly |
isChecked | checked |
isLoaded | loaded |
isIndeterminate | indeterminate |
| v2 | v3 |
|---|---|
colorScheme | colorPalette |
noOfLines | lineClamp |
truncated | truncate |
spacing (Stack) | gap |
apply | textStyle or layerStyle |
// v2 — sx with nested pseudo-selectors
<Box sx={{ "&:hover": { color: "blue.500" } }} />
// v3 — css prop with "&" selectors
<Box css={{ "&:hover": { color: "blue.500" } }} />
| v2 | v3 |
|---|---|
Modal | Dialog |
FormControl | Field |
Select | NativeSelect |
AlertDialog | AlertDialog (compound, see below) |
Modal is the most common rename — every <Modal>, <ModalOverlay>,
<ModalContent>, <ModalHeader>, <ModalBody>, <ModalFooter>, and
<ModalCloseButton> becomes a Dialog.* compound part:
// v2
<Modal isOpen={open} onClose={onClose}>
<ModalOverlay />
<ModalContent>
<ModalHeader>Title</ModalHeader>
<ModalBody>Body</ModalBody>
<ModalFooter><Button onClick={onClose}>Close</Button></ModalFooter>
</ModalContent>
</Modal>
// v3
<Dialog.Root open={open} onOpenChange={({ open }) => setOpen(open)}>
<Dialog.Backdrop />
<Dialog.Positioner>
<Dialog.Content>
<Dialog.Header><Dialog.Title>Title</Dialog.Title></Dialog.Header>
<Dialog.Body>Body</Dialog.Body>
<Dialog.Footer><Button onClick={() => setOpen(false)}>Close</Button></Dialog.Footer>
<Dialog.CloseTrigger />
</Dialog.Content>
</Dialog.Positioner>
</Dialog.Root>
v3 adopts a consistent compound component API. The codemod handles many of these, but complex custom usage needs manual review.
Checkbox
// v2
<Checkbox isChecked={val} onChange={fn}>Label</Checkbox>
// v3
<Checkbox.Root checked={val} onCheckedChange={fn}>
<Checkbox.Control><Checkbox.Indicator /></Checkbox.Control>
<Checkbox.Label>Label</Checkbox.Label>
</Checkbox.Root>
Progress
// v2
<Progress value={60} colorScheme="blue" />
// v3
<Progress.Root value={60} colorPalette="blue">
<Progress.Track><Progress.Range /></Progress.Track>
</Progress.Root>
Accordion
// v2
<Accordion><AccordionItem><AccordionButton /><AccordionPanel /></AccordionItem></Accordion>
// v3
<Accordion.Root>
<Accordion.Item value="item-1">
<Accordion.ItemTrigger />
<Accordion.ItemContent />
</Accordion.Item>
</Accordion.Root>
FormControl → Field
// v2
<FormControl isInvalid={!!error} isRequired>
<FormLabel>Email</FormLabel>
<Input type="email" />
<FormErrorMessage>{error}</FormErrorMessage>
<FormHelperText>We'll never share your email.</FormHelperText>
</FormControl>
// v3
<Field.Root invalid={!!error} required>
<Field.Label>Email</Field.Label>
<Input type="email" />
<Field.ErrorText>{error}</Field.ErrorText>
<Field.HelpText>We'll never share your email.</Field.HelpText>
</Field.Root>
All FormControl sub-parts map to Field.*:
FormLabel → Field.LabelFormErrorMessage → Field.ErrorTextFormHelperText → Field.HelpTextFormControl props isInvalid, isRequired, isDisabled → invalid,
required, disabledDialog / Drawer / Menu / Tabs follow the same compound pattern: use
ComponentName.Root, .Trigger, .Content, .Item, etc. Check the Chakra UI
v3 docs for the specific compound API for each.
// v2 — @chakra-ui/next-js
import { LinkOverlay } from "@chakra-ui/next-js"
// v3 — asChild pattern
import NextLink from "next/link"
<ChakraLink asChild><NextLink href="/about">About</NextLink></ChakraLink>
import NextImage from "next/image"
<ChakraImage asChild><NextImage src="..." alt="..." /></ChakraImage>
// v3 — single component (recipe)
import { defineRecipe } from "@chakra-ui/react"
// v2
const buttonStyle = {
baseStyle: { fontWeight: "bold" },
variants: { solid: { bg: "blue.500" } },
defaultProps: { variant: "solid" },
}
const buttonRecipe = defineRecipe({
base: { fontWeight: "bold" },
variants: { variant: { solid: { bg: "blue.500" } } },
defaultVariants: { variant: "solid" },
})
// v3 — slot recipe
import { defineSlotRecipe } from "@chakra-ui/react"
// v2 — multiStyleConfig (multi-part component)
const cardStyle = multiStyleConfig({
parts: ["root", "header"],
baseStyle: { root: { bg: "white" }, header: { fontWeight: "bold" } },
})
const cardSlotRecipe = defineSlotRecipe({
slots: ["root", "header"],
base: { root: { bg: "white" }, header: { fontWeight: "bold" } },
})
After adding custom tokens, semantic tokens, recipes, or slot recipes, run typegen to keep TypeScript types in sync:
npx @chakra-ui/cli typegen ./theme.ts
Complex theme migrations — if you're moving a large v2 theme with many custom tokens, semantic tokens, or multi-part component styles, use the
chakra-ui-themingskill. It covers the full token/recipe/slot-recipe API in depth and is a better guide than this section alone.
<Provider> in app/layout.tsx (Server Component — no "use client")components/ui/provider.tsx already has "use client"suppressHydrationWarning to <html> to prevent color mode flicker"use client"// pages/_app.js
import { Provider } from "@/components/ui/provider"
export default function App({ Component, pageProps }) {
return (
<Provider>
<Component {...pageProps} />
</Provider>
)
}
Remove any ColorModeScript from pages/_document.tsx — it is not used in v3.
Work through this after the migration is complete:
npm install / pnpm installnpx tsc --noEmit — resolve all type errorsnpm run lintnpm run buildgrep -r "ColorModeScript\|useColorModeValue\|extendTheme\|styleConfig\|@chakra-ui/icons\|@chakra-ui/next-js" src/
If the user's version, framework, or scope is ambiguous, ask:
@chakra-ui/react are you on right now?"State assumptions clearly if you proceed without asking.