05. Your React app needs to support dark mode. How do you implement it?
Short answer
Define colors as CSS custom properties and switch them with a data-theme attribute on the root element, defaulting to the OS setting via prefers-color-scheme. Keep the user's choice (light, dark or system) in React context and persist it in localStorage. Apply the theme with a tiny blocking script before React loads so there's no flash of the wrong theme. Styling stays in CSS, so switching themes doesn't re-render the whole app.
Why it happens
Common problems with naive implementations:
- Flash of incorrect theme: React reads
localStorageafter the first paint, so users see light mode briefly. - Theme in JS objects (e.g. passing colors through context to every component) re-renders the whole tree on toggle and is hard to keep consistent.
- Ignoring the OS preference, or not reacting when it changes.
- SSR hydration mismatch: the server doesn't know the user's theme, so the markup differs from the client.
- Native controls and scrollbars stay light because the
color-schemeproperty isn't set.
How to fix it
- Tokens in CSS variables, overridden per theme.
- System default with
prefers-color-scheme, overridden by an explicit choice. - Inline script in the document head that sets
data-themebefore first paint. - Theme context for the toggle; it only updates the attribute and storage.
- Listen to OS changes when the choice is
system.
:root {
--bg: #ffffff;
--text: #111827;
--accent: #2563eb;
color-scheme: light;
}
:root[data-theme="dark"] {
--bg: #0b1120;
--text: #e5e7eb;
--accent: #60a5fa;
color-scheme: dark;
}
body {
background: var(--bg);
color: var(--text);
}
<!-- in the document head, before the app bundle -->
<script>
(function () {
try {
var saved = localStorage.getItem("theme") || "system";
var dark =
saved === "dark" ||
(saved === "system" && matchMedia("(prefers-color-scheme: dark)").matches);
document.documentElement.dataset.theme = dark ? "dark" : "light";
} catch (e) {}
})();
</script>
import { createContext, useContext, useEffect, useState } from "react";
const ThemeContext = createContext(null);
export function ThemeProvider({ children }) {
const [choice, setChoice] = useState(
() => localStorage.getItem("theme") ?? "system"
);
useEffect(() => {
const media = matchMedia("(prefers-color-scheme: dark)");
const apply = () => {
const dark = choice === "dark" || (choice === "system" && media.matches);
document.documentElement.dataset.theme = dark ? "dark" : "light";
};
apply();
localStorage.setItem("theme", choice);
media.addEventListener("change", apply);
return () => media.removeEventListener("change", apply);
}, [choice]);
return (
<ThemeContext.Provider value={{ choice, setChoice }}>
{children}
</ThemeContext.Provider>
);
}
export const useTheme = () => useContext(ThemeContext);
For SSR (Next.js), read localStorage only on the client (the inline script handles first paint), add suppressHydrationWarning on the root element because the script changes its attribute, or use a library like next-themes. Tailwind supports this with a dark: variant configured to use the data-theme attribute.
How to verify
- Toggle the OS theme with "system" selected: the app follows without reload.
- Hard reload in dark mode with CPU throttling: no white flash.
- Check contrast ratios (WCAG AA, 4.5:1 for body text) in both themes.
- Check form controls, scrollbars, images and charts in dark mode.
- No hydration warnings in the console for SSR apps.
Follow-up questions
- Why CSS variables instead of a JS theme object? The browser restyles without React re-rendering, and non-React parts (portals, third-party widgets) pick up the theme.
- How do you sync across tabs? Listen to the
storageevent and update the choice. - How about images? Use the
pictureelement with aprefers-color-schememedia query, or a CSS filter for icons.
Quick recap
- CSS variables +
data-themeon the root. - Default to
prefers-color-scheme, store explicit choice. - Blocking head script prevents theme flash.
- Context only manages the choice, not every color.
- Check contrast and
color-schemefor native UI.