Chakra UI v2 Theme Overrides Not Rendering: Diagnostic Guide

The Problem and What to Check First

Custom colors, font sizes, or component styles defined with `extendTheme` sometimes do not reach Chakra UI components. A button keeps the default Chakra blue, a custom variant is ignored, or text styles fall back to the built-in theme. There is often no error message, which makes the failure silent.

Useful takeaway: most missing overrides come from one of three places—the extended theme never reaches `ChakraProvider`, the override is keyed under the wrong path inside `theme.components`, or the installed Chakra packages are version-mismatched. This guide assumes Chakra UI v2 with React 18.

Recognizable Condition

You are likely hitting this issue when:

• Values from `extendTheme` such as custom colors or font sizes do not appear on screen.
• Components render with default Chakra theme values instead of your overrides.
• Some overrides work while others do not, suggesting a partial path or merge problem.

Cause and Diagnostic Table

Symptom	Likely cause	Where to check
No overrides apply anywhere in the app	Extended theme object is not passed to `ChakraProvider`	App root component and provider props
Component styles ignore `baseStyle` or `variants`	Override keyed under the wrong component sub-path	`theme.components.[ComponentName]`
Colors work in light mode but not dark mode	Missing dark mode key or incorrect color mode reference	`theme.colors` structure or `useColorModeValue`
Theme object looks correct but styles do not change	Component is a plain HTML element or an unstyled wrapper	Component import and rendered JSX
Overrides exist but conflict with defaults	Version mismatch between `@chakra-ui/react` and `@chakra-ui/theme`	Installed package versions

Ordered Checks

1. Confirm `ChakraProvider` receives the extended theme

   Open your application entry point. `ChakraProvider` must wrap the component tree and receive the theme returned by `extendTheme` through its `theme` prop. If you create a theme but never pass it, components use the default Chakra theme.

2. Inspect the theme object at runtime

   Add a temporary log inside any component rendered beneath the provider:

   import { useTheme } from '@chakra-ui/react';
   
   function ThemeInspector() {
     const theme = useTheme();
     console.log('components.Button', theme.components?.Button);
     return null;
   }
   

   If `theme.components.Button` is undefined or missing your override, the theme was not merged correctly or was never provided.

3. Verify the component is a Chakra UI component

   Your override targets `components.Button`, so the rendered element must import `Button` from `@chakra-ui/react`. A plain `` element or a custom wrapper that does not forward Chakra props will not read theme overrides.

4. Check the override path and variant name

   Chakra UI v2 organizes component overrides under `theme.components.[ComponentName]`. Common sub-keys are `baseStyle`, `defaultProps`, and `variants`. If you define `variants.brand` but render ``, the lookup fails because variant names are case-sensitive.

5. Align package versions

   Run this in your project root to inspect installed versions:

   npm ls @chakra-ui/react @chakra-ui/theme
   

   Expected check: both packages should report version 2.x. A mismatch can cause the theme shape expected by `@chakra-ui/react` to differ from the shape produced by `extendTheme`. This command is read-only and carries no state-change risk.

Fixes Tied to Findings

Pass the extended theme to the provider

If your app root creates a theme but renders `ChakraProvider` without it, pass the theme explicitly:

import { extendTheme, ChakraProvider } from '@chakra-ui/react';

const theme = extendTheme({
  colors: {
    brand: {
      500: '#2563eb',
    },
  },
});

export default function App() {
  return (
    
      {/* component tree */}
    
  );
}

Correct the component override path

In Chakra UI v2, button style overrides belong under `components.Button`, not at the top level or under a generic `components.styles` key:

const theme = extendTheme({
  components: {
    Button: {
      baseStyle: {
        fontWeight: 'semibold',
      },
      variants: {
        solid: {
          colorScheme: 'brand',
        },
      },
    },
  },
});

Then use the variant by its exact key:

Branded button

Handle color mode structure

If your custom color needs different values per mode, define it with light and dark keys or consume it with `useColorModeValue`. Referencing a top-level color token that lacks a dark-mode counterpart can make the override disappear when the user switches color modes.

Align dependency versions

If `npm ls` shows mismatched major versions, adjust them to match the Chakra UI v2 line. Do not copy theme overrides from a Chakra UI v1 project; the theme structure is not interchangeable between major versions.

Verification

After applying a fix, render a component that uses the override and inspect it in browser DevTools:

1. Open the Elements panel and select the rendered component.
2. Open the Computed styles pane and look for the custom color, font weight, or variant value.
3. Confirm the value matches your `extendTheme` definition rather than the Chakra default.

As a secondary check, log `theme.components.Button` inside a component before rendering. If the override object is present but still not reflected in styles, the issue may be component selection or variant naming rather than theme delivery.

To isolate framework-specific causes, reproduce the provider and theme setup in a minimal Vite or Create React App project with `@chakra-ui/react`. If the override works there but not in your main application, the cause is likely Next.js server-side rendering, custom webpack configuration, or another wrapper around the provider.

Limitations

• `extendTheme` merges shallowly by default. Nested component overrides may require full object replacement or a dedicated merge utility rather than simple spreading.
• Chakra UI v1 and v2 theme structures are not interchangeable. Do not port v1 overrides into a v2 project without restructuring them.
• Server-side rendering frameworks can hydrate color mode or theme context differently. If mismatches appear only after hydration, verify client-only rendering or provider placement relative to SSR boundaries.

Escalation Criteria

Escalate when overrides remain missing after you confirm all of the following:

• `ChakraProvider` at the app root receives the extended theme.
• `theme.components.[ComponentName]` contains the expected override object.
• The rendered element is the Chakra UI component, not a plain HTML element.
• Package versions for `@chakra-ui/react` and `@chakra-ui/theme` match.

If the issue still reproduces in a minimal Chakra-only sandbox without Next.js or custom webpack configuration, file a bug report. Include the theme snippet, the component usage, and the browser DevTools computed styles showing the missing value.