Sponsor

Customize Theme

By default, all Chakra components inherit values from the default theme. In some scenarios, you might need to customize the default theme to match your design requirements, you have a few different options depending on your goals.

Customize the theme tokens like colors, font sizes, line heights, etc.
Customize the component styles, changing the base styles, sizes, or variants.
Customize the global styles.

Customizing theme tokens#

To extend or override a token in the default theme, import the extendTheme function and add the keys you'd like to override. You can also add new values to the theme.

For example, if you'd like to update the colors in the theme to include your brand colors, here's what you'll do:

// 1. Import `extendTheme`
import { extendTheme } from "@chakra-ui/core"

// 2. Call `extendTheme` and pass your custom values
const theme = extendTheme({
  colors: {
    brand: {
      100: "#f7fafc",
      // ...
      900: "#1a202c",
    },
  },
})

// 3. Now you can use this colors in your components
function Usage() {
  return <Box bg="brand.100">Welcome</Box>
}

// 1. Import `extendTheme`
import { extendTheme } from "@chakra-ui/core"
// 2. Call `extendTheme` and pass your custom values
const theme = extendTheme({
  colors: {
    brand: {
      100: "#f7fafc",
      // ...
      900: "#1a202c",
    },
  },
})
// 3. Now you can use this colors in your components
function Usage() {
  return <Box bg="brand.100">Welcome</Box>
}

If you're curious what theme styles you can override, please reference the default theme foundation style files.

Customizing component styles#

Chakra has a specific approach or API for styling components. The main idea is most components have default or base styles (baseStyle), styles for different sizes (sizes), and styles for different visual variants (variants).

It's important to understand this so you can override any component style effectively.

You're not limited to the component styles that Chakra providers, you can also create your custom component styles. Learn more.

Customizing single components#

As we mentioned earlier, a component style consists of baseStyles, sizes, variants and an optional defaultProps to denote the default size or variant.

Here's what the component style object looks like:

const ComponentStyle = {
  // style object for base or default style
  baseStyle: {},
  // styles for different sizes ("sm", "md", "lg")
  sizes: {},
  // styles for different visual variants ("outline", "solid")
  variants: {},
  // default values for `size` and `variant`
  defaultProps: {
    size: "",
    variant: "",
  },
}

const ComponentStyle = {
  // style object for base or default style
  baseStyle: {},
  // styles for different sizes ("sm", "md", "lg")
  sizes: {},
  // styles for different visual variants ("outline", "solid")
  variants: {},
  // default values for `size` and `variant`
  defaultProps: {
    size: "",
    variant: "",
  },
}

For example, let's override the component styles for Chakra's Button component.

// theme.js
import { extendTheme } from "@chakra-ui/core"

const theme = extendTheme({
  components: {
    Button: {
      // 1. We can update the base styles
      baseStyle: {
        fontWeight: "bold", // Normally, it's "semibold"
      },
      // 2. We can add a new button size or extend existing
      sizes: {
        xl: {
          h: "56px",
          fontSize: "lg",
          px: "32px",
        },
      },
      // 3. We can add a new visual variant
      variants: {
        "with-shadow": {
          bg: "red.400",
          boxShadow: "0 0 2px 2px #efdfde",
        },
        // 4. We can override existing variants
        solid: (props) => ({
          bg: "red.400",
        }),
      },
    },
  },
})

export default theme

// theme.js
import { extendTheme } from "@chakra-ui/core"
const theme = extendTheme({
  components: {
    Button: {
      // 1. We can update the base styles
      baseStyle: {
        fontWeight: "bold", // Normally, it's "semibold"
      },
      // 2. We can add a new button size or extend existing
      sizes: {
        xl: {
          h: "56px",
          fontSize: "lg",
          px: "32px",
        },
      },
      // 3. We can add a new visual variant
      variants: {
        "with-shadow": {
          bg: "red.400",
          boxShadow: "0 0 2px 2px #efdfde",
        },
        // 4. We can override existing variants
        solid: (props) => ({
          bg: "red.400",
        }),
      },
    },
  },
})
export default theme

And that's it! When you use the Button from Chakra, these updates will be automatically applied.

<Button size="xl" variant="with-shadow">
  Welcome
</Button>

<Button size="xl" variant="with-shadow">
  Welcome
</Button>

If you're curious what component styles you can override, please reference the default component style files.

Customizing global styles#

Global styles are theme-aware styles you can applied to any html element globally.

To add global styles, update the theme.styles.global key in the theme. Global styles can be a style object or a function that returns a style object.

// theme.js
import { extendTheme } from "@chakra-ui/core"
import { mode } from "@chakra-ui/core"

// Version 1: Using objects
const theme = extendTheme({
  styles: {
    global: {
      // styles for the `body`
      body: {
        bg: "gray.400",
        color: "white",
      },
      // styles for the `a`
      a: {
        color: "teal.500",
        _hover: {
          textDecoration: "underline",
        },
      },
    },
  },
})

// Version 2: Using functions
const overrides = extendTheme({
  styles: {
    global: (props) => ({
      body: {
        fontFamily: "body",
        color: mode("gray.800", "whiteAlpha.900")(props),
        bg: mode("white", "gray.800")(props),
        lineHeight: "base",
      },
    }),
  },
})

// theme.js
import { extendTheme } from "@chakra-ui/core"
import { mode } from "@chakra-ui/core"
// Version 1: Using objects
const theme = extendTheme({
  styles: {
    global: {
      // styles for the `body`
      body: {
        bg: "gray.400",
        color: "white",
      },
      // styles for the `a`
      a: {
        color: "teal.500",
        _hover: {
          textDecoration: "underline",
        },
      },
    },
  },
})
// Version 2: Using functions
const overrides = extendTheme({
  styles: {
    global: (props) => ({
      body: {
        fontFamily: "body",
        color: mode("gray.800", "whiteAlpha.900")(props),
        bg: mode("white", "gray.800")(props),
        lineHeight: "base",
      },
    }),
  },
})

Scaling out your project#

As your project grows in size, it's best to keep things organized. We highly suggest that instead of a single theme.js (or theme.ts) file, that you create a /theme folder in its place. Inside of this folder, you could have a directory structure that looks like such:

/theme
  - index.js  # my main theme entrypoint
  - styles.js  # all my global style overrides
  /foundations
    - borders.js  # all my border overrides
  /components
    - button.js  # all my button overrides

/theme
  - index.js  # my main theme entrypoint
  - styles.js  # all my global style overrides
  /foundations
    - borders.js  # all my border overrides
  /components
    - button.js  # all my button overrides

This way, you can structure your main theme entrypoint file to be much cleaner, like this:

// theme.js
import { extendTheme } from "@chakra-ui/core"

// Global style overrides
import styles from "./styles.js"

// Foundational style overrides
import border from "./foundations/borders"

// Component style overrides
import Button from "./components/button"

const overrides = {
  styles,
  borders,
  // Other foundational style overrides go here
  components: {
    Button,
    // Other components go here
  },
}

export default extendTheme(overrides)

// theme.js
import { extendTheme } from "@chakra-ui/core"
// Global style overrides
import styles from "./styles.js"
// Foundational style overrides
import border from "./foundations/borders"
// Component style overrides
import Button from "./components/button"
const overrides = {
  styles,
  borders,
  // Other foundational style overrides go here
  components: {
    Button,
    // Other components go here
  },
}
export default extendTheme(overrides)

None of this is strictly required to use Chakra - but we've learned some hard lessons on the "right" way and the "wrong" way to write styles. The above is our best suggestion on how to write style overrides and organize your custom theme.

In the next section, we'll show some examples of how to create custom component styles and use them in your components!

Edit this page