Chakra UI v2 useColorMode SSR hydration mismatch persists despite documented workarounds

Answer the question first

To fully remove the hydration warning and the flash of the wrong theme, combine a server-side theme source (a cookie or the Accept-CH/Sec-CH-Prefers-Color-Scheme client hint) with a lightweight pre-hydration script that sets data-theme before React mounts. This works under a strict CSP because the script can be served as an external same-origin file, avoiding Chakra's inline ColorModeScript entirely.

Why the mismatch still occurs

• The server renders without knowledge of the user's localStorage value.
• When React hydrates, it reads localStorage, sees a different value, and writes a new data-theme attribute, triggering a warning and a visible flash.

Confirmed facts

• Chakra v2 accepts an initialColorMode value via its theme config, which can be driven by server-rendered props.
• A cookie (commonly named chakra-ui-color-mode) is a CSP-friendly way to persist the preference and make it readable on the server.
• An external script can set document.documentElement.dataset.theme before React mounts without violating script-src 'self'.

Step-by-step pattern

1. Server side: read the theme source

   // Next.js example
   export async function getServerSideProps({ req }) {
     const cookie = req.headers.cookie?.match(/chakra-ui-color-mode=([^;]+)/);
     const mode = cookie ? cookie[1] : null;
     return { props: { initialColorMode: mode } };
   }

2. Pass the value into the Chakra theme config

   import { ChakraProvider, extendTheme } from '@chakra-ui/react';
   
   export default function App({ Component, pageProps }) {
     const theme = extendTheme({
       config: { initialColorMode: pageProps.initialColorMode ?? 'system' }
     });
     return (
       <ChakraProvider theme={theme}>
         <Component {...pageProps} />
       </ChakraProvider>
     );
   }

3. Client side: keep the normal hook and sync the cookie

   import { useEffect } from 'react';
   import { useColorMode } from '@chakra-ui/react';
   
   function ThemeToggle() {
     const { colorMode, toggleColorMode } = useColorMode();
     useEffect(() => {
       document.cookie = `chakra-ui-color-mode=${colorMode}; path=/; max-age=31536000`;
     }, [colorMode]);
     return <button onClick={toggleColorMode}>Toggle</button>;
   }

4. External pre-hydration script

   // public/color-mode.js
   (function () {
     var stored = localStorage.getItem('chakra-ui-color-mode');
     if (stored === 'dark' || stored === 'light') {
       document.documentElement.dataset.theme = stored;
     } else {
       var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
       document.documentElement.dataset.theme = prefersDark ? 'dark' : 'light';
     }
   })();

   Include it in _document with <script src="/color-mode.js"></script> in the <head>. Serve it with Content-Type: application/javascript and ensure your CSP's script-src allows 'self'.

Community helpers

• next-themes is a widely used zero-config option that handles cookie-based server detection plus client synchronization, and it can be adapted to drive Chakra's color mode. Verify its current CSP behavior against your policy before adopting.
• Next.js middleware can refresh the cookie on each request so SSR always reads a current value.

Accessibility note

Deferring useColorMode initialization until after hydration removes the flash but leaves a short window with no theme applied, which can affect users relying on high-contrast or reduced-motion preferences. The cookie-plus-external-script pattern avoids that window entirely, which is why it is the recommended approach over deferred initialization.

One diagnostic detail that changes the recommendation

Does your CSP permit a nonce or hash for inline scripts? If yes, you can keep the documented inline ColorModeScript with a nonce and skip the external file. If inline code is strictly forbidden, the external script above is the reliable path.