How to Prevent Theme Flash in a React: Instant Dark Mode Switching

When implementing dark mode in a React application, a common problem arises: when the app loads, the initial HTML is displayed with the default light theme before JavaScript executes and applies the user's saved theme. This results in a "flash" effect where the page briefly appears in the wrong theme before correcting itself. Understanding the Problem When a web application loads, the browser first renders index.html. The JavaScript file responsible for React and theming loads afterward. If the theme is stored in localStorage, React applies it only after hydration. This leads to a noticeable flicker, especially for users who prefer dark mode. Solution: Applying the Theme Before React Loads To eliminate this issue, we can apply the saved theme immediately using a small inline script in index.html. This script runs before the HTML is rendered, ensuring that the correct theme is applied instantly. Implementation Add the following script inside the section of index.html: const THEME_ATTRIBUTE_KEY = 'data-theme'; const GET_THEME = () => { const isDeviceDark = window.matchMedia('(prefers-color-scheme: dark)').matches; return localStorage.getItem(THEME_ATTRIBUTE_KEY) || (isDeviceDark ? 'dark' : 'light'); }; const SET_THEME = (themeValue) => { document.documentElement.removeAttribute('data-theme'); document.documentElement.setAttribute('data-theme', themeValue); document.querySelector("meta[name='theme-color']") ?.setAttribute('content', themeValue === 'dark' ? '#1c1c1e' : '#ffffff'); localStorage.setItem(THEME_ATTRIBUTE_KEY, themeValue); }; const theme = GET_THEME(); SET_THEME(theme); How It Works This script runs immediately when index.html loads, before React initializes. It reads the user's theme preference from localStorage or detects the system preference. It applies the theme by setting the data-theme attribute (light or dark) on the element. It also sets the theme-color meta tag for a more cohesive experience on mobile devices. Why Update meta[name='theme-color']? The tag is especially useful for mobile users. It controls the color of the browser’s UI elements, such as the address bar in Chrome on Android. Updating it dynamically ensures that the UI blends seamlessly with the selected theme. Alternative Approach and Its Downsides A quick way to prevent the theme flicker is to add a simple inline script that applies the stored theme immediately: (function () { const theme = localStorage.getItem("theme") || "light"; document.documentElement.setAttribute("data-theme", theme); })(); This ensures that the theme is applied before React loads, avoiding the white flash. However, there's a downside to this approach: we now have duplicate logic. Since this script only runs on page load, we still need a separate function in React to switch themes dynamically when the user toggles between dark and light mode. Why Keeping All Logic in One Place Is Better In our approach, we define reusable functions: The script in index.html ensures the theme is set instantly. The same functions are used inside React components. No need for duplicate logic—theme switching is handled in one place. This makes the implementation more maintainable and scalable. Using TypeScript for Better Type Safety If you're using TypeScript in your React project, you can declare the global functions and constants in a separate .d.ts file to ensure type safety: declare const SET_THEME: (themeValue: 'light' | 'dark') => void; declare const GET_THEME: () => 'light' | 'dark'; declare const THEME_ATTRIBUTE_KEY: string; This allows you to use these functions in your React components with full TypeScript support: const theme = GET_THEME(); const handleThemeToggle = () => { SET_THEME(theme === 'light' ? 'dark' : 'light'); }; By doing this, TypeScript will catch any incorrect usage of these global functions, making your code more robust and maintainable. Potential Drawbacks and Considerations While this solution is effective, there are a few potential downsides to keep in mind: 1. Global Function Names Could Cause Conflicts Declaring SET_THEME and GET_THEME globally may lead to conflicts in larger projects with multiple scripts. To avoid this, you can encapsulate them within an object attached to window: window.themeUtils = { SET_THEME, GET_THEME }; Then, in React, you can access them like this: const theme = window.themeUtils.GET_THEME(); window.themeUtils.SET_THEME(theme === 'light' ? 'dark' : 'light'); 2. localStorage May Not Always Be Available In some cases, such as when browsing in private mode on certain browsers, localStorage may be restricted. To handle this, wrap localStorage calls in try-catch: const safeLocalStorageGet = (key) => { try { return localStorage.getItem(key); } catch {

Apr 4, 2025 - 13:25

How to Prevent Theme Flash in a React: Instant Dark Mode Switching

When implementing dark mode in a React application, a common problem arises: when the app loads, the initial HTML is displayed with the default light theme before JavaScript executes and applies the user's saved theme. This results in a "flash" effect where the page briefly appears in the wrong theme before correcting itself.

Understanding the Problem

When a web application loads, the browser first renders index.html.
The JavaScript file responsible for React and theming loads afterward.
If the theme is stored in localStorage, React applies it only after hydration.
This leads to a noticeable flicker, especially for users who prefer dark mode.

Solution: Applying the Theme Before React Loads

To eliminate this issue, we can apply the saved theme immediately using a small inline script in index.html. This script runs before the HTML is rendered, ensuring that the correct theme is applied instantly.

Implementation

Add the following script inside the section of index.html:

How It Works

This script runs immediately when index.html loads, before React initializes.
It reads the user's theme preference from localStorage or detects the system preference.
It applies the theme by setting the data-theme attribute (light or dark) on the element.
It also sets the theme-color meta tag for a more cohesive experience on mobile devices.

Why Update `meta[name='theme-color']`?

The tag is especially useful for mobile users. It controls the color of the browser’s UI elements, such as the address bar in Chrome on Android. Updating it dynamically ensures that the UI blends seamlessly with the selected theme.

Alternative Approach and Its Downsides

A quick way to prevent the theme flicker is to add a simple inline script that applies the stored theme immediately:

This ensures that the theme is applied before React loads, avoiding the white flash.

However, there's a downside to this approach: we now have duplicate logic.
Since this script only runs on page load, we still need a separate function in React to switch themes dynamically when the user toggles between dark and light mode.

Why Keeping All Logic in One Place Is Better

In our approach, we define reusable functions:

The script in index.html ensures the theme is set instantly.
The same functions are used inside React components.
No need for duplicate logic—theme switching is handled in one place.

This makes the implementation more maintainable and scalable.

Using TypeScript for Better Type Safety

If you're using TypeScript in your React project, you can declare the global functions and constants in a separate .d.ts file to ensure type safety:

declare const SET_THEME: (themeValue: 'light' | 'dark') => void;
declare const GET_THEME: () => 'light' | 'dark';
declare const THEME_ATTRIBUTE_KEY: string;

This allows you to use these functions in your React components with full TypeScript support:

const theme = GET_THEME();

const handleThemeToggle = () => {
    SET_THEME(theme === 'light' ? 'dark' : 'light');
};

By doing this, TypeScript will catch any incorrect usage of these global functions, making your code more robust and maintainable.

Potential Drawbacks and Considerations

While this solution is effective, there are a few potential downsides to keep in mind:

1. Global Function Names Could Cause Conflicts

Declaring SET_THEME and GET_THEME globally may lead to conflicts in larger projects with multiple scripts. To avoid this, you can encapsulate them within an object attached to window:

window.themeUtils = { SET_THEME, GET_THEME };

Then, in React, you can access them like this:

const theme = window.themeUtils.GET_THEME();
window.themeUtils.SET_THEME(theme === 'light' ? 'dark' : 'light');

2. `localStorage` May Not Always Be Available

In some cases, such as when browsing in private mode on certain browsers, localStorage may be restricted. To handle this, wrap localStorage calls in try-catch:

const safeLocalStorageGet = (key) => {
  try {
    return localStorage.getItem(key);
  } catch {
    return null;
  }
};

Then update the theme retrieval function:

const GET_THEME = () => {
  const isDeviceDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
  return safeLocalStorageGet(THEME_ATTRIBUTE_KEY) || (isDeviceDark ? 'dark' : 'light');
};

3. Hardcoded `light` and `dark` values

If your application requires additional themes beyond just "light" and "dark," you’ll need a more flexible approach. One option is to store an array of available themes and validate the stored value before applying it:

const AVAILABLE_THEMES = ['light', 'dark', 'solarized'];

const GET_THEME = () => {
  const savedTheme = localStorage.getItem(THEME_ATTRIBUTE_KEY);
  return AVAILABLE_THEMES.includes(savedTheme) ? savedTheme : 'light';
};

const SET_THEME = (themeValue) => {
  if (AVAILABLE_THEMES.includes(themeValue)) {
    /// code
  }
};

Conclusion

By applying the theme instantly in index.html, we avoid the unwanted flash of the wrong theme during initial load. This simple yet effective technique significantly improves the user experience in React applications with theme switching.

As mentioned earlier, the method provided above might not work for all scenarios. However, I aimed to address the most common case that you might encounter, and this solution is generally sufficient for React applications with theme switching. Although it is slightly compromising, it strikes a good balance between simplicity and functionality for many typical use cases.

To help you make an informed decision, I have highlighted some potential pitfalls and edge cases. If you encounter specific problems or need further details, feel free to reach out, and I can expand the article to cover more specific cases and solutions.