customizing Chakra UI theme in a Gatsby project
Tags: gatsby, react, webdev, beginners
Published: 2020-05-19 18:49:38

So this is going to be my first post on DEV.to :tada:

In this article, I'm going to explain how to add your own custom themes to your Gatsby project.

## TL;DR

1. create a new file in `src/gatsby-plugin-chakra-ui/theme.js`
2. import original theme from `@chakra-ui/core` & add your own properties
3. restart server

## prerequisites

- gatsby project is set up 
- `gatsby-plugin-chakra-ui` is added to your project

If you haven't added the plugin yet, check out the [docs](https://www.gatsbyjs.org/packages/gatsby-plugin-chakra-ui) on how to do so.

## step 1: add a theme.js file

Create a a `theme.js` file under `src/gatsby-plugin-chakra-ui/`.
(Most likely you need add the `gatsby-plugin-chakra-ui` folder under `src` )

This will allow Gatsby to **shadow** the `theme.js` file.

**Shadowing** is a concept introduced by Gatsby so users can use their own themes.
What this does is that it replaces a file in the webpack bundle with a file in the `src` directory.
For example, if you have a plugin named `gatsby-plugin-awesome` and you want to replace `awesomeFile.js` with your own version, you would create a new file in `src/gatsby-plugin-awesome/awesomeFile.js`.
Then you can use your own version of `awesomeFile.js` in your project instead of the default version provided by the plugin.

[This comment on Github Issues](https://github.com/chakra-ui/chakra-ui/issues/347#issuecomment-579620254) is also another explanation on shadowing. 

## step 2: edit `theme.js`

This is where we write our custom theme.

I'm going to add a custom color called "brandPurple" that has a value of "#673FB4".

First, we'll copy & paste the code from the [plugin docs](https://www.gatsbyjs.org/packages/gatsby-plugin-chakra-ui/).

```javascript
// src/gatsby-plugin-chakra-ui/theme.js
const theme = {};

export default theme;
```

This code is overwriting the default theme provided by the plugin with an empty theme.

:warning: Don't try to run `gatsby develop` with this code yet; you're going to see a bunch of errors because the theme object is `{}`, and none of the previously available values can be accessed.

Next, we're going to add the default theme provided by Chakra UI to our custom theme.

```javascript
// src/gatsby-plugin-chakra-ui/theme.js
import { theme as defaultTheme } from "@chakra-ui/core"

const theme = {
  ...defaultTheme
};

export default theme;
```

We rename `theme as defaultTheme` because we don't want names to clash for Chakra UI's theme with our own variable `theme`.

You can run `gatsby develop` with this code now, but you won't see any changes, because we haven't added anything to our theme yet.

Finally, we add our own "brandPurple" color like so:


```javascript
// src/gatsby-plugin-awesome/theme.js
import { theme as defaultTheme } from "@chakra-ui/core"

const theme = {
  ...defaultTheme,
  colors: {
    ...defaultTheme.colors,
    brandPurple: "#673FB4",
  },
}

export default theme
```

### final code

```javascript
// src/gatsby-plugin-awesome/theme.js

import { theme as defaultTheme } from "@chakra-ui/core"

const theme = {
  ...defaultTheme,
  colors: {
    ...defaultTheme.colors,
    brandPurple: "#673FB4",
  },
}

export default theme
```

## step 3: restart server

In order for the `theme.js` to shadow, we need to restart the server.
Go ahead and hit Ctrl+C (or other shortcut keys depending on your computer), and enter `gatsby develop`

At this point, we're all set and we can use our new "brandPurple" color just like any other theme colors provided by Chakra UI.

Here's an example test code.

```javascript
// src/pages/testPage.js
import React from "react"
import { Box } from "@chakra-ui/core"

const TestPage = () => {
  <Box bg="brandPurple">
    here's the new color!
  </Box>
}

export default TestPage
```

see also: [plugin docs](), [Chakra UI docs on custom themes]()


Feel free to leave a comment or hit me up on Twitter if you have any questions.