Gatsby

Chakra UI is a great UI library to get your Gatsby website up and running fast. The setup is slightly different than other projects, however the API usage seen in the rest of the docs is the same!

Installation#

Gatsby plugins make external APIs plug-and-play into your website. Installing can be done with the following command:

npm i @chakra-ui/gatsby-plugin @chakra-ui/react @emotion/react @emotion/styled framer-motion

yarn add @chakra-ui/gatsby-plugin @chakra-ui/react @emotion/react @emotion/styled framer-motion

pnpm add @chakra-ui/gatsby-plugin @chakra-ui/react @emotion/react @emotion/styled framer-motion

bun add @chakra-ui/gatsby-plugin @chakra-ui/react @emotion/react @emotion/styled framer-motion

For Chakra v3 -- to reduce maintenance costs across the repo -- we are deprecating the plugin. Below is the recommended approach to set up the provider to allow for complete user-end flexibility.

Setting up Chakra locally#

To set up the Chakra Provider, you apply it as a root element in gatsby-browser.js

// gatsby-browser.jsx
import * as React from 'react'
import { ChakraProvider } from '@chakra-ui/react'

// Import your extended theme from a location in `./src`
import { customTheme } from './src/theme'

export const wrapRootElement = ({ element }) => (
  // Or ChakraBaseProvider if you only want to compile the default Chakra theme tokens
  <ChakraProvider theme={customTheme}>{element}</ChakraProvider>
)

And you are using SSR, also add this to gatsby-ssr.js. Additionally, include the color mode script to assist in color mode flashing.

// gatsby-ssr.jsx

import * as React from 'react'
import { ChakraProvider, ColorModeScript } from '@chakra-ui/react'

// Import your extended theme from a location in `./src`
import { customTheme } from './src/theme'

export const onRenderBody = ({ setPreBodyComponents }) => {
  setPreBodyComponents([
    <ColorModeScript
      initialColorMode={customTheme.config.initialColorMode}
      key='chakra-ui-no-flash'
    />,
  ])
}

export const wrapRootElement = ({ element }) => (
  // Or ChakraBaseProvider if you only want to compile the default Chakra theme tokens
  <ChakraProvider theme={customTheme}>{element}</ChakraProvider>
)

If you use gatsby-ssr.js with gatsby-browser.js you can import the root element setup from a reusable component file.

// ./src/provider.tsx
import * as React from 'react'
import { ChakraProvider } from '@chakra-ui/react'

import { customTheme } from './theme'

export const WrapRootElement = ({ element }) => (
  // Or ChakraBaseProvider if you only want to compile the default Chakra theme tokens
  <ChakraProvider theme={customTheme}>{element}</ChakraProvider>
)

Gatsby Starter#

Alternatively, you can run a Gatsby Starter to have everything you need already set up

gatsby new {your-project-name} https://github.com/chakra-ui/gatsby-starter-chakra-ui-ts

This includes

TypeScript
Chakra UI and needed dependencies
Local setup of the Chakra provider
Basic Gatsby Boilerplate and Config

Usage#

After installation, you'll need to add @chakra-ui/gatsby-plugin to the gatsby-config.js file.

Once we deprecate the plugin, this configuration for it should simply be removed.

// gatsby-config.js

module.exports = {
  plugins: [
    {
      resolve: '@chakra-ui/gatsby-plugin',
      options: {
        /**
         * @property {boolean} [resetCSS=true]
         * if false, this plugin will not use `<CSSReset />
         */
        resetCSS: true,
        /**
         * @property {number} [portalZIndex=undefined]
         * The z-index to apply to all portal nodes. This is useful
         * if your app uses a lot z-index to position elements.
         */
        portalZIndex: undefined,
      },
    },
  ],
}

The theme setup below will also be deprecated as you can create a simple theme directory to house the extended theming to then import into the provider at gatsby-browser.js

To use a custom theme, you can shadow this plugin’s theme.js file with your own theme:

// src/@chakra-ui/gatsby-plugin/theme.js
import { extendTheme } from '@chakra-ui/react'
const theme = {
  colors: {
    primary: 'rebeccapurple',
  },
}

export default extendTheme(theme)

If you want to use the default theme there's no need to shadow the file.

Migration Notes#

From v1.x to v2.x#

The isUsingColorMode option was removed. The ChakraProvider will always use the ColorModeProvider
The isResettingCSS option was renamed to resetCSS

From v0.8.x to v1.x#

The Gatsby plugin has been renamed from gatsby-plugin-chakra-ui to @chakra-ui/gatsby-plugin. Please make sure to have updated this when installing Chakra UI in your next Gatsby project.

Edit this page on GitHub