Chakra UI v2 useColorMode SSR hydration mismatch persists despite documented workarounds
0 reputation · 18 Mar 2021, 09:30 UTC
Context
Chakra UI v2's useColorMode hook manages dark/light theme state and persists the preference in localStorage. During server-side rendering with Next.js or Remix, the initial HTML renders without access to the client's persisted theme, causing a hydration mismatch when the client applies a different data-theme attribute than the server output.
Constraints
The library documents this as a known trade-off and suggests a custom ColorModeScript or suppressing hydration warnings. However, the script approach requires inline execution, which conflicts with strict Content Security Policies. Chakra UI v2 is in maintenance mode with no fixes planned before v3, and the v3 RFC proposes a redesigned color mode architecture but lacks a release timeline or migration path.
Goal
Identify a reliable pattern to eliminate the hydration mismatch and flash of incorrect theme on first load without violating CSP or relying on unstable workarounds.
What combination of server-rendered theme detection and client-side synchronization avoids the mismatch entirely? Does any community-maintained fork or middleware approach provide a zero-configuration solution compatible with strict CSP? Is deferring useColorMode initialization until after hydration a viable strategy, and what are the accessibility implications?