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

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
• Chakra Gatsby Plugin
• Basic Gatsby Boilerplate and Config

Usage#

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

// 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,
      },
    },
  ],
}

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.