A dark theme without the flash: a switcher that remembers the choice

You turned on a dark theme, and on every reload the page flashes white for a split second before it goes dark. This is the most common mistake in a theme switcher, and it is fixed with one tiny script in the right place. Below is the whole recipe: code you can copy, an explanation of how it works, and a way to check the result yourself.

What you will get #

• By default the theme matches the system theme (light or dark) and works even with JavaScript turned off.
• A button switches the theme, and the choice is remembered in the browser.
• The saved choice is applied before the first paint: no white flash on reload.

Why the page flashes #

Step 1. Declare that the site has both themes #

<meta name="color-scheme" content="light dark">
<script>
(function () {
  var saved = null;
  try { saved = localStorage.getItem('theme'); } catch (e) {}
  if (saved === 'light' || saved === 'dark') {
    document.documentElement.dataset.theme = saved;
  }
})();
</script>

Step 2. Describe the colours once #

:root {
  color-scheme: light dark;
  --bg: light-dark(#ffffff, #14161a);
  --text: light-dark(#1b1f24, #e6e8eb);
  --card: light-dark(#f3f5f8, #1e2228);
  --line: light-dark(#d8dee6, #2c333c);
  --accent: light-dark(#1a56db, #7aa7ff);
}
:root[data-theme="light"] { color-scheme: light; }
:root[data-theme="dark"] { color-scheme: dark; }
body { background: var(--bg); color: var(--text); }

Step 3. Add a button #

<button id="theme-toggle" type="button" aria-pressed="false"></button>

(function () {
  var root = document.documentElement;
  var button = document.getElementById('theme-toggle');
  var names = { dark: 'Dark', light: 'Light' };

  function current() {
    return root.dataset.theme ||
      (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
  }
  function show() {
    var now = current();
    button.textContent = names[now];
    button.setAttribute('aria-pressed', now === 'dark');
  }

  button.addEventListener('click', function () {
    var next = current() === 'dark' ? 'light' : 'dark';
    root.dataset.theme = next;
    try { localStorage.setItem('theme', next); } catch (e) {}
    show();
  });
  show();
})();

Check it yourself #

The rest is checked too: without JavaScript the page takes the system theme, after pressing the button and reloading the choice stays, and at 390, 768 and 1280 points there is no horizontal scroll.
You can repeat it like this:

1. Open the page, press the button and choose the dark theme.
2. Turn on network throttling in the developer tools and reload the page: the background stays dark from the first frame.
3. Turn off JavaScript and clear the storage: the page follows the system theme again.

Common mistakes #

• The script at the end of the page. The flash comes back: the choice is known too late.
• No color-scheme on :root. Without it, light-dark() does not know which value to take.
• No try around localStorage. In private mode the page breaks in some browsers.
• The theme in JavaScript only. Without the script the visitor has no dark theme even if the system has one turned on. The recipe solves this with color-scheme.
• Contrast not checked. Text and background should give at least 4.5 to 1, the WCAG AA accessibility rule. Check both themes, not one.