Chakra UI (v2) - Removing Default Styles and Tokens

Overview

This post explores how to remove CSS color variables and other tokens from Chakra UI's default theme configuration. I originally wrote this as an answer on Stack Overflow on November 28, 2023, and expanded information for this post.

Maybe you like having your dev tools free of extra CSS variables that you don't intend to use. This article explores how you can override the Chakra UI theme via manual merging.

Chakra UI Theme Customization Options

ChakraProvider

The ChakraProvider provides theme tokens and component theming, typically including two or more variants for each component.

ChakraBaseProvider

The ChakraBaseProvider provides the theme tokens (colors, spacing, etc.) like ChakraProvider, but omits the default component theming.

If you intend to theme component styles yourself and want to cut down size, ChakraBaseProvider is worth exploring.

Theme Extension

Chakra UI's extendTheme utility merges your changes with the default Chakra UI theme so you can enjoy the styling Chakra UI has already done for you, while still allowing you to override pieces of it with your own customized styling.

What if you don't want to simply replace a value for extra Chakra UI tokens you're not using, but omit them all together?

Using Object Merging To Omit Chakra UI Theme Items

Before we look at merging away Chakra UI tokens and styles, it's helpful to understand which ones are used in Chakra UI components. If we remove tokens that other Chakra UI styles rely on, then we're going to have rendering oddities.

Required Colors

Let's use colors as an example. If we take a look at Chakra UI's color semantic tokens definition , we can see a variety of color schemes and some utility tokens like transparent and current.

After spending a lot of time with Chakra UI's codebase, I've noticed some patterns in component styling.

1. Many components default to gray colorScheme.
2. black and white are used often.
3. Many components use blackAlpha and whiteAlpha for hover styles
4. current and transparent are used often for color inheritance and to maintain border widths.

If we omit these tokens, it would be wise to first do a refactor to look for where these color tokens are used and change them to something else, or to ensure that they're included in our own theme override.

Customize Theme with Spread Syntax

One method to combine two objects while selectively omitting properties is to use spread syntax . Spread syntax allows expanding an existing object into a new object.

While the upside to spread syntax is flexibility, the downside is verbosity. For each layer where a modification is applied, the base theme needs to be spread into that layer for it to still be applied.

The example below creates a merged theme with Chakra UI's imported default theme and custom colors. Chakra UI colors are omitted with the exception of the few commonly used colors, which are added back into the colors theme.

import {theme, type Colors} from "@chakra-ui/react";

// Add our brand colors
const customColors: Colors = {
    brand: {
        50: "#f5faff",
        100: "#eaf2ff",
        200: "#c8dfff",
        300: "#a6ccff",
        400: "#63a3ff",
        500: "#208aff",
        600: "#1d74e6",
        700: "#174fb4",
        800: "#123a89",
        900: "#0d275e",
    }
}
export const mergedTheme: Record<keyof typeof theme, unknown> = {
    // Spread in the Chakra UI default theme
    ...theme,
    // Override colors
    colors: {
        // Add back in Chakra UI base colors used heavily in theme styles
        black: "#000000",
        blackAlpha: {...theme.colors.blackAlpha},
        currentColor: "currentColor",
        gray: {...theme.colors.gray},
        transparent: "transparent",
        white: "#ffffff",
        whiteAlpha: {...theme.colors.whiteAlpha},

        // Add custom colors
        ...customColors,
    },
    // Override borders
    borders: {
        // Add in Chakra UI base borders
        ...theme.borders,

        // Add custom borders
        "3px": "3px solid",
    }
}

What about Object.assign()?

Object.assign() isn't a great fit for deeply nested objects, because it has the same layering limitations as spread syntax. Spread syntax would still need to be used to merge back in nested properties.

Customize Theme with Merge Utilities

There are many deep merge utilities available on npm, like lodash , or TypeScript-friendly equivalents moderndash , radash , and remeda that can merge deeply nested objects.

How to use these utilities won't be covered in this post, but it is helpful to know tools like this are out there.