When customizing a Chakra UI theme using the extendTheme utility, developers can define styles at multiple levels, including global design tokens, component base styles, and specific variants. There is uncertainty regarding the exact resolution order when a component is defined within the components object of the theme, but also receives style props directly on the React element. Specifically, it is unclear how the internal merge logic handles conflicts between a theme-defined baseStyle and a specific variant when both target the same CSS property. Which level of the theme hierarchy takes precedence when a variant and a baseStyle overlap? Does the component-level style prop always override the theme's variant definition regardless of the property's specificity?

Chakra UI extendTheme Style Priority Order

1 answer

33775 reputation · 24 Aug 2024, 18:21 UTC

In Chakra UI, when using `extendTheme`, the resolution of component styles follows a specific inheritance hierarchy. When multiple definitions target the same CSS property, the later definition in the merge chain overrides the lower-priority one.

The Priority Hierarchy

The order of precedence, from **lowest to highest**, is as follows:

Global Styles: Defined in the `globalStyles` object.
Base Style: The default styles applied to all instances of a component.

Variants:

variant={...quot}

Inline Style Props: Props passed directly to the React element (e.g., <Button bg="red">).

Base Style vs. Variant Resolution

If a baseStyle and a variant overlap on the same CSS property, the variant takes precedence. This is because the Chakra theme engine first merges the base styles into the component and then merges the specific variant styles on top of that result.

Inline Props vs. Theme Definitions

The component-level style prop (inline prop) always overrides the theme's variant definition, regardless of the property's CSS specificity. This occurs because inline props are applied during the final stage of the component rendering process after all theme-based styles have been computed.

Example Resolution Logic

const theme = extendTheme({
  components: {
    Button: {
      baseStyle: { fontSize: 4, bg: 'gray' },
      variants: {
        brand: { bg: 'blue' } // Overrides 'gray'
      }
    }
  }
});

// Result: 
// <Button variant="brand"> → bg is blue
// <Button variant="brand" bg="green"> → bg is green (Inline wins)

Note: This behavior assumes you are using standard Chakra UI component patterns. If you are using custom components with manual mergeStyles calls, the order may vary based on your implementation.

Your perspective belongs here.

Join the conversation

To build on the priority hierarchy, it is important to note that extendTheme performs a deep merge of the theme configuration. This means that when you override a specific variant in your custom theme, you aren't replacing the entire variant object, but rather merging your changes into the existing default variant.

For example, if the default solid variant defines both bg and color, and your extendTheme only specifies a new bg for that variant, the default color remains intact. This additive behavior ensures that partial overrides don't accidentally strip away necessary default styles.

Version Note

This merge logic applies to Chakra UI v2. If you are using v3, the system has transitioned to createSystem and a recipe-based model, which handles style resolution and merging differently. It is recommended to verify your package.json version to ensure these extendTheme behaviors align with your installation.

What is the priority order for nested component style overrides in extendTheme?