Getting Started with Next.js

Installation

In your Next.js project, install Chakra UI by running either of the following:

npm i @chakra-ui/react @emotion/react@^11 @emotion/styled@^11 framer-motion@^6

yarn add @chakra-ui/react @emotion/react@^11 @emotion/styled@^11 framer-motion@^6

Provider Setup

After installing Chakra UI, you need to set up the ChakraProvider at the root of your application.

Go to pages/_app.js or pages/_app.tsx (create it if it doesn't exist) and wrap the Component with the ChakraProvider:

// pages/_app.js
import { ChakraProvider } from "@chakra-ui/react";

function MyApp({ Component, pageProps }) {
  return (
    <ChakraProvider>
      <Component {...pageProps} />
    </ChakraProvider>
  );
}

export default MyApp;

Customizing theme

If you intend to customise the default theme object to match your design requirements, you need to extend the theme.

Chakra UI provides an extendTheme function that deep merges the default theme with your customizations.

pages/_app.js
import { ChakraProvider } from "@chakra-ui/react";

// 1. Import the extendTheme function
import { extendTheme } from "@chakra-ui/react";

// 2. Extend the theme to include custom colors, fonts, etc
const colors = {
  brand: {
    900: "#1a365d",
    800: "#153e75",
    700: "#2a69ac",
  },
};

const theme = extendTheme({ colors });

// 3. Pass the `theme` prop to the `ChakraProvider`
function MyApp({ Component, pageProps }) {
  return (
    <ChakraProvider theme={theme}>
      <Component {...pageProps} />
    </ChakraProvider>
  );
}

export default MyApp;

tip

To further customize components or build your own design system, the theme-tools package includes useful utilities.

Color Mode Script

The color mode script needs to be added before the content inside the body tag for local storage syncing to work correctly.

tip

When setting the initial color mode, we recommend adding it as a config to your theme and reference that in the ColorModeScript. To use ColorModeScript on a site with strict Content-Security-Policy, you can use the nonce prop that will be passed to the <script> tag.

pages/_document.js
import { ColorModeScript } from "@chakra-ui/react";
import { Html, Head, Main, NextScript } from "next/document";
import theme from "./theme";

export default function Document() {
  return (
    <Html lang="en">
      <Head />
      <body>
        {/* 👇 Here's the script */}
        <ColorModeScript initialColorMode={theme.config.initialColorMode} />
        <Main />
        <NextScript />
      </body>
    </Html>
  );
}

Notes on TypeScript 🚨

Please note that when adding Chakra UI to a TypeScript project, a minimum TypeScript version of 4.1.0 is required.

ChakraProvider Props

Name	Type	Default	Description
resetCSS	`boolean`	`true`	automatically includes `<CSSReset />`
theme	`Theme`	`@chakra-ui/theme`	optional custom theme
colorModeManager	`StorageManager`	`localStorageManager`	manager to persist a users color mode preference in
portalZIndex	`number`	`undefined`	common z-index to use for `Portal`

Installation​

Provider Setup​

Customizing theme​

Color Mode Script​

Notes on TypeScript 🚨​

ChakraProvider Props​