Which approach resolves Chakra UI’s hydration mismatch for color mode?

Answer

Override getInitialColorMode to read a cookie that stores the user’s preferred color mode. Set that cookie on the client after detecting the preference (via localStorage or window.matchMedia). This makes the server render the same mode as the client, eliminating the hydration mismatch.

Confirmed facts

• Chakra UI calls getInitialColorMode on both server and client during hydration; differing values trigger a React hydration warning and a flash of the wrong theme.
• On the server localStorage is unavailable, so the default light mode is used unless another source (e.g., a cookie) supplies the preference.
• A meta‑tag such as <meta name="color-scheme"> only influences the browser’s default UI, not Chakra UI’s internal color‑mode state, so it cannot resolve the mismatch on its own.

Steps to implement

1. On the client, after the component mounts, detect the preferred mode:

   const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
   const stored = localStorage.getItem('chakra-color-mode');
   const mode = stored || (prefersDark ? 'dark' : 'light');
   // Save the mode as a cookie (e.g., using js-cookie or document.cookie)
   document.cookie = `chakra-color-mode=${mode}; path=/; SameSite=Lax; Max-Age=31536000`;
   

2. In your Chakra provider, override getInitialColorMode:

   import { ChakraProvider, extendTheme } from '@chakra-ui/react'
   
   function getInitialColorMode() {
     // Read the cookie synchronously; return null if not found
     const match = document.cookie.match(/(^| )chakra-color-mode=([^;]+)/);
     return match ? match[2] : null;
   }
   
   const theme = extendTheme({})
   
   function App() {
     return (
       
         {/* your app */}
       
     )
   }
   

3. Deploy the app with SSR enabled. The server will now read the cookie and render the correct data-chakra-color-mode attribute, matching the client’s hydration.

Missing diagnostic detail

To confirm that this approach will work for your deployment, verify whether the cookie is being sent with the initial SSR request. If the cookie is absent on the first request, the first load will still mismatch until the cookie is set on a subsequent visit.