Chakra UI Color Mode Persistence in SSR Builds: Choosing the Source of Truth

The Recommended Approach for Static Generation

When using Chakra UI v2.x with Next.js Pages Router and static generation (SSG), the client's localStorage must be the source of truth. Because the server cannot access client-side storage and you have no per-request cookies, any specific mode rendered on the server is a guess that will likely lead to a hydration mismatch or a visual flash (FOUC) when the client-side state takes over.

Implementation Strategy

The most appropriate approach is to suppress the server-rendered output of the color mode state while using a blocking script to prevent the theme flash. This avoids the conflict between initialColorMode and localStorage by deferring the final theme application to the client, but doing so before the browser paints the body.

1. Inject a Blocking Script: Place a small, vanilla JavaScript snippet in the <head> of your _document.js. This script should read localStorage and manually apply the corresponding CSS class (e.g., chakra-ui-light or chakra-ui-dark) to the html or body element.
2. Configure the Provider: Set the ColorModeProvider to use the theme's initialColorMode as the baseline, but rely on the blocking script to override it immediately upon page load.
3. Handle Hydration: Use suppressHydrationWarning on the html element to prevent React from complaining about the attribute difference between the server-generated HTML and the script-modified DOM.

Handling Missing or Invalid Preferences

When the stored value is absent or unparseable, the fallback logic should follow this priority chain:

• System Preference: Check window.matchMedia('(prefers-color-scheme: dark)').matches. This ensures the first-time user experience matches their OS settings.
• Theme Default: Fall back to the initialColorMode defined in your Chakra theme configuration.

Verification Steps

To verify the implementation is working without causing a flash:

• Throttled Connection: Use Chrome DevTools Network throttling (Slow 3G). If you see the default theme for a split second before the stored theme appears, the blocking script is either missing or executing too late.
• Storage Clear: Clear localStorage and verify the page loads using the system preference or initialColorMode.
• HTML Inspection: View the page source (Ctrl+U). The server-rendered HTML should not contain a hardcoded color mode class if you are relying entirely on the client-side script for the initial paint.

Note: This recommendation assumes you are not using a Middleware layer to inject cookies; if you introduce a cookie-based system, the source of truth shifts to the server.