Using Chakra UI in Next.js (Pages)

A guide for installing Chakra UI with Next.js pages directory

Templates

Use one of the following templates to get started quickly. The templates are configured correctly to use Chakra UI.

Next.js app template

Next.js pages template

Installation

The minimum node version required is Node.20.x

Install dependencies

npm i @chakra-ui/react @emotion/react

Add snippets

Snippets are pre-built components that you can use to build your UI faster. Using the @chakra-ui/cli you can add snippets to your project.

npx @chakra-ui/cli snippet add

Update tsconfig

If you're using TypeScript, you need to update the compilerOptions in the tsconfig file to include the following options:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "skipLibCheck": true,
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

If you're using JavaScript, create a jsconfig.json file and add the above code to the file.

Setup provider

Wrap your application with the Provider component at the root of your application.

This provider composes the following:

ChakraProvider from @chakra-ui/react for the styling system
ThemeProvider from next-themes for color mode

pages/_app.tsx

import { Provider } from "@/components/ui/provider"

export default function App({ Component, pageProps }: AppProps) {
  return (
    <Provider>
      <Component {...pageProps} />
    </Provider>
  )
}

In the pages/_document.tsx file, add the suppressHydrationWarning prop to the html element.

pages/_document.tsx

import { Head, Html, Main, NextScript } from "next/document"

export default function Document() {
  return (
    <Html suppressHydrationWarning>
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

Optimize Bundle

We recommend using the experimental.optimizePackageImports feature in Next.js to optimize your bundle size by loading only the modules that you are actually using.

next.config.mjs

export default {
  experimental: {
    optimizePackageImports: ["@chakra-ui/react"],
  },
}

This also helps to resolve warnings like:

[webpack.cache.PackFileCacheStrategy] Serializing big strings (xxxkiB)

Enjoy!

With the power of the snippets and the primitive components from Chakra UI, you can build your UI faster.

import { Button } from "@/components/ui/button"
import { HStack } from "@chakra-ui/react"

const Demo = () => {
  return (
    <HStack>
      <Button>Click me</Button>
      <Button>Click me</Button>
    </HStack>
  )
}

Next.js (App)

Remix