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 @chakra-ui/next-js @emotion/react @emotion/styled framer-motion

yarn add @chakra-ui/react @chakra-ui/next-js @emotion/react @emotion/styled framer-motion

pnpm add @chakra-ui/react @chakra-ui/next-js @emotion/react @emotion/styled framer-motion

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;

App Directory Setup#

Next.js 13 introduces a new app/ directory / folder structure. By default it uses Server Components. However, Chakra UI only works in client-side components.

To use Chakra UI in server components, you need to convert them into client-side component by adding a 'use client'; at the top of your file.

We've also provided a @chakra-ui/next-js package that gives you a smoother experience when using Chakra UI in the app directory.

This package provides the CacheProvider which composes the Emotion.js' cache provider with the useServerInsertedHTML hook from next/navigation. This is necessary to ensure that computed styles are included in the initial server payload (during streaming).

To use Chakra UI in app directory, you can wrap ChakraProvider and CacheProvider in your own client Component.

// app/providers.tsx
'use client'

import { CacheProvider } from '@chakra-ui/next-js'
import { ChakraProvider } from '@chakra-ui/react'

export function Providers({ 
    children 
  }: { 
  children: React.ReactNode 
  }) {
  return (
    <CacheProvider>
      <ChakraProvider>
        {children}
      </ChakraProvider>
    </CacheProvider>
  )
}

Now, you can import and render <Providers /> directly within your root. With the providers rendered at the root, all the components and hooks from Chakra UI will work as expected within your own Client Components.

// app/layout.tsx
import { Providers } from "./providers";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Providers>
          {children}
        </Providers>
      </body>
    </html>
  );
}

The 'use client' directive is still required to be added to the top of the page-related file.

If you're not using the new app/ directory, there's no need to add the'use client'; directive at the top of your file.

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',
  },
}

export 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

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.

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 './_app'

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`

Chakra UI with Next.js Link#

If you're using Next.js 13, we've provided a @chakra-ui/next-js package that gives you a smoother experience when using Chakra UI Link component with next/link.

This package provides the Link which combines the functionality of the Next.js Link and Chakra UI Link components.

// app/page.tsx
'use client'
import { Link } from '@chakra-ui/next-js'

export default function Page() {
  return (
    <Link href='/about' color='blue.400' _hover={{ color: 'blue.500' }}>
      About
    </Link>
  )
}

Chakra UI with next/font#

With Next.js 13, you can optimize your fonts (including custom fonts) and remove external network requests for improved privacy and performance.

To use the new next/font with Chakra UI globally;

/* pages/_app.tsx */
import { Rubik } from 'next/font/google';

const rubik = Rubik({ subsets: ['latin'] });

const App = ({ Component, pageProps }: AppProps) => {
  <>
    <style jsx global>
      {`
        :root {
          --font-rubik: ${rubik.style.fontFamily};
        }
      `}
    </style>
    <ChakraProvider theme={theme}>
      <Component {...pageProps} />
    </ChakraProvider>
  </>
};

Now you can use the optimized font with your custom theme file across the app.

/* theme.ts */
import { extendTheme } from "@chakra-ui/react";

export const theme = extendTheme({
  ...
    fonts: {
      heading: 'var(--font-rubik)',
      body: 'var(--font-rubik)',
    }
  ...
});

Edit this page on GitHub