Persisting Theme and Preventing Flash

When a page loads, React must download, parse, and execute JavaScript before it can read localStorage and apply the correct theme. During this gap, the browser renders using the default styles. If the user prefers dark mode but your default is light, they see a brief white flash before the theme corrects itself.

The fix is an inline script placed in the document head that runs synchronously before any other code. This script reads localStorage immediately and sets data-theme on document.documentElement. Because it is a blocking script, the browser applies the attribute before painting any content.

Async or deferred scripts run after the HTML is parsed and potentially after the first paint. That defeats the entire purpose. The blocking inline script must have no async or defer attributes and must not be loaded from an external file. The script must be tiny to minimize the performance cost.

The blocking script is minimal: read localStorage.getItem('theme'), check window.matchMedia('(prefers-color-scheme: dark)').matches as a fallback, then call document.documentElement.setAttribute('data-theme', theme). Wrap it in a try-catch in case localStorage is unavailable in private browsing.

In Next.js, use the Script component from next/script with strategy="beforeInteractive" inside _document.js. The beforeInteractive strategy injects the script into the page HTML before any page JavaScript runs, achieving the same blocking behavior in the Next.js build pipeline.

In a Vite or Create React App project, edit index.html directly and place the inline script tag in the head before any other scripts. Since index.html is the entry point for the browser, the script runs before React boots. Keep it concise to stay under 100 bytes.

In a server-rendered app, the server can read the theme from a cookie sent with the request. The server then sets data-theme in the rendered HTML before sending it to the browser. This avoids any client-side flash entirely because the correct theme is in the very first byte of HTML.

The complete flow is: browser downloads HTML, parser encounters blocking inline script, script reads localStorage and sets data-theme, parser continues, page is painted with correct theme, React hydrates and picks up the same theme from localStorage. The user sees one consistent theme from the start.

To verify the fix works, open Chrome DevTools, go to the Network tab, and throttle to Slow 3G. Reload the page. If you see a theme change during load, the flash is not fixed. With the blocking script in place, the initial paint should already show the correct theme even on slow connections.

If your React initial state defaults to light but the blocking script set dark before hydration, React may warn about a hydration mismatch. Avoid this by initializing React theme state by also reading localStorage during the initial render, ensuring the React-rendered HTML matches the DOM state set by the blocking script.

Storybook and test environments do not load your index.html, so the blocking script never runs. Provide a decorator or test setup that applies a default data-theme attribute in those environments. This prevents confusing visual inconsistencies when developing components in isolation.

What type of script must be used in the document head to prevent the flash of wrong theme?

Prevent the flash of wrong theme by injecting a tiny inline blocking script in the document head that reads localStorage and sets data-theme before any paint. In Next.js use strategy="beforeInteractive", in Vite/CRA add it directly to index.html. SSR apps can read a cookie to set the theme server-side.