Introduction

Migrating from Chakra UI v2 to v3 is an important step toward improving performance, accessibility, and maintainability. The official migration guide provides a great starting point, but through my experience, I encountered several nuances that required additional adjustments. This guide is a refined, detailed version that ensures a smoother migration process based on practical implementation and real-world challenges. Mainly we concentrate on a bit more advanced usage of migration from the deprecated themeStyles to the new slots and recipes approach.

---

Preparation

Before beginning the migration, it is important to prepare your project and development environment to avoid breaking changes affecting production.

1. Review the Official Migration Guide

• The official migration guide highlights the key changes and breaking updates in Chakra UI v3.
• Familiarize yourself with the changes to avoid unexpected issues during the migration.

2. Analyze Your Dependencies

• Ensure that your dependencies, especially React, Emotion, and Framer Motion, are compatible with Chakra v3.
• Identify any custom components or heavy Chakra usage that may need refactoring.

3. Create a Separate Migration Branch

• Use a separate Git branch to migrate safely and test changes incrementally.
• This allows for easy rollbacks and debugging without affecting the production environment.

---

Key Changes in v3

Chakra UI v3 introduces various enhancements and breaking changes. Below are the most significant updates that require adjustments in your project.

1. Updated Theming System

Chakra UI v3 enhances the theming system by introducing recipes (also known as slot recipes), making it easier to manage reusable and modular styles.

Chakra UI v2 (Traditional Theme Config)

const buttonTheme = {
  baseStyle: {
    fontWeight: 'bold',
    borderRadius: 'md',
  },
};

export default buttonTheme;

Chakra UI v3 (Using defineRecipe)

import { defineRecipe } from '@chakra-ui/react';

const buttonRecipe = defineRecipe({
  base: {
    fontWeight: 'bold',
    borderRadius: 'md',
  },
});

export default buttonRecipe;

Chakra UI v3 introduces defineSlotRecipe for theming multipart components such as Accordions, simplifying style structuring.

Chakra UI v2 (Multipart Style Config)

import { accordionAnatomy } from '@chakra-ui/anatomy';
import { createMultiStyleConfigHelpers } from '@chakra-ui/react';

const { definePartsStyle, defineMultiStyleConfig } = createMultiStyleConfigHelpers(
  accordionAnatomy.keys
);

const custom = definePartsStyle({
  panel: {
    border: '1px solid',
    borderColor: 'gray.200',
    background: 'gray.50',
    borderRadius: 'full',
  },
});

export const accordionTheme = defineMultiStyleConfig({
  variants: { custom },
});

Chakra UI v3 (defineSlotRecipe)

import { defineSlotRecipe } from '@chakra-ui/react';
import { accordionAnatomy } from '@chakra-ui/react/anatomy';

const accordionSlotRecipe = defineSlotRecipe({
  slots: accordionAnatomy.keys(),
  base: {
    root: {
      width: 'full',
      display: 'flex',
      flexDirection: 'column',
      gap: '16px',
    },
    itemIndicator: {
      color: 'black',
      _icon: {
        boxSize: '24px',
        strokeWidth: '1px',
      },
    },
    itemBody: {
      pt: '0',
      pb: '0',
    },
  },
});

export default accordionSlotRecipe;

2. Chakra CLI

The Chakra UI CLI provides powerful tools to streamline development workflows. Below are two key features that can assist in migration and customization.

Chakra Snippet

Chakra UI CLI includes a snippet generator, enabling quick scaffolding of reusable component snippets.

Generating Snippets into a Directory

npx @chakra-ui/cli snippet add --outdir ./src/shared/components/ui

Adding a Custom Script to package.json

To streamline snippet management, add the following script to package.json:

{
  "scripts": {
    "chakra-add-snippet": "npx @chakra-ui/cli snippet add --outdir ./src/shared/components/ui"
  }
}

Chakra Eject

Chakra UI v3 introduces an eject command that generates a file containing all the default theme tokens and recipes. This serves as a strong foundation for those who want to build a customized theme.

Generating Default Theme Tokens and Recipes

Run the following command to generate all the default Chakra UI theme tokens and recipes into a specified directory:

npx @chakra-ui/cli eject --outdir ./src/theme

This command exports the default Chakra UI theme into the src/theme directory, allowing for further customization.

3. Hooks Updates

Chakra UI v3 removes the dedicated hooks package in favor of external libraries such as react-use and usehooks-ts. Instead of relying on Chakra’s built-in hooks, it is now recommended to use these third-party solutions.

The only hooks now shipped with Chakra UI are:

• useBreakpointValue
• useCallbackRef
• useDisclosure
• useControllableState
• useMediaQuery

If your project previously used Chakra-specific hooks, ensure you migrate to equivalent alternatives in react-use or usehooks-ts where applicable.

---

Step-by-Step Migration

1. Update Dependencies

• Remove unused dependencies that are no longer required:

npm uninstall @emotion/styled framer-motion

• Install updated versions of the necessary packages:

npm install @chakra-ui/react@latest @emotion/react@latest

• Install component snippets using the Chakra CLI:

npx @chakra-ui/cli snippet add

2. Update Theme Configuration

• Replace existing theme.ts or theme.js with the new structure.

3. Refactor Components

• Update components to align with breaking changes.
• Adjust modal, popover, and drawer components for enhanced accessibility.

4. Test and Verify

• Conduct automated and manual testing to ensure UI components render correctly.

---

Conclusion

Migrating to Chakra UI v3 brings significant improvements in performance, maintainability, and accessibility. While changes can be challenging, this guide provides a structured approach to ensure a smooth transition. Adapt these recommendations to your specific project needs and enjoy the enhanced features of Chakra UI v3.

Happy coding! 🚀