Upgrading to v2

Chakra UI v2 is focused on providing compatibility for React 18. Doing so we had to introduce some breaking changes. That lead us to remove some features that we deprecated previously.

tip

Still using v0 and want to upgrade to v1? Go here

---

Upgrade steps

Here is a list of steps to migrate your project to v2.

1. Update your dependencies

Make sure you update all @chakra-ui packages you use to @chakra-ui/<package-name>@2.0.0 and your react dependencies to at least v18

caution

Chakra UI v2 is not backwards compatible with React v17 and lower. Make sure to upgrade to React v18.

Here is how your dependencies could look like:

{
  "dependencies": {
    "@chakra-ui/react": "^2.0.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "devDependencies": {
    "@types/react": "^18.0.0",
    "@types/react-dom": "^18.0.0"
  }
}

Step 2 and 3 are only necessary if you used the mentioned functions in your project.

2. Update createStandaloneToast

We had to make some changes to the our createStandaloneToast function, because of changes in the way React 18 works.

Chakra UI v1 rendered the toast container DOM element for you. The usage of createStandaloneToast could look like this:

import { createStandaloneToast } from "@chakra-ui/toast";

const toast = createStandaloneToast();
toast({ title: "Chakra UI" });

In v2 you need to render the ToastContainer in your application code. This allows you have only one React root in your application.

Here is an example on how to update your code:

import * as ReactDOM from "react-dom/client";
import { createStandaloneToast } from "@chakra-ui/toast";

const { ToastContainer, toast } = createStandaloneToast();

// render the ToastContainer in your React root
const rootElement = document.getElementById("root");
ReactDOM.createRoot(yourRootElement).render(
  <>
    <App />
    <ToastContainer />
  </>
);

toast({ title: "Chakra UI" });

info

Please note: There are no breaking changes to the hook useToast. There are only breaking changes to createStandaloneToast.

3. Color mode update

Color mode transition

Ensure the transition between light/dark modes happens instantly without transition. This helps to avoid a weird UX when switch modes for elements with different transition definition on the page.

To opt out of this feature, set theme.config.disableTransitionOnChange to false.

Using custom storage keys

Allow user configure the storage key for the provider and script. We now export a createLocalStorageManager and createCookieStorageManager functions.

const manager = createLocalStorageManager("my-key");

function App({ Component, pageProps }) {
  return (
    <ChakraProvider colorModeManager={manager}>
      <Component {...pageProps} />
    </ChakraProvider>
  );
}

If you use ColorModeScript, you'll need to configure the storageKey from script as well.

<ColorModeScript storageKey="my-key" />

Improved cookie support

Add support for using cookie storage in color mode script. To use cookie script, you can set type prop to cookie.

<ColorModeScript type="cookie" />

Color mode precedence

Refactored color mode to behave consistently between provider and script. The new precedence is as follows:

• Get the color mode value in the specified localStorage or cookie
• If value doesn't exist, use the initialColorMode value specified.
  • If the initial value is system, then we'll compute the color mode using window.matchMedia(...)
  • else, we use the initial value as is.
• If user specifies useSystemColorMode: true, we'll subscribe to color mode changes from the operating system.

Breaking changes

• In the theme's config, the useSystemColorMode property is no longer used to determine the initial color mode. To achieve that, please use initialColorMode: "system".

  It is now used to only determine whether to subscribe to color mode changes from the operating system.

• We removed the references to --chakra-ui-color-mode. Use the data-theme property instead

4. Deprecated features

We removed some previously deprecated features from Chakra UI v2. Here is a detailed list of affected components or packages:

Button, Icon Button, Input, NumberInput, Radio, Checkbox, Select

We removed the isFullWidth prop from these components. Use width="full" or width="100%" instead.

Checkbox

We removed the defaultIsChecked prop from the Checkbox component. Use the defaultChecked prop instead.

Hooks

We removed the useEventCallback hook

Grid

We removed the area prop from the Grid component. You can pass it to the GridItem component instead.

Styled system

We removed the d style prop. Use written out display prop instead.

We removed the isTruncated style prop. You can use noOfLines={1} instead.

Theme

We removed deprecated types.

---

That's it! Welcome to Chakra UI v2 🥳.

info

If you still experience issues after migrating, feel free to create an issue or join our Discord chat here: discord.gg/chakra-ui.