Dark Mode Toggle Using JavaScript: Complete Implementation Guide

A dark mode toggle using JavaScript needs to solve three things at once: read the user's saved preference, respect their OS setting when no preference exists yet, and apply the theme before the page actually renders to avoid a jarring flash of the wrong color scheme.

01Dark Mode Toggle Using JavaScript: The Core Pattern

The pattern practitioners call the "preference cascade" checks three sources in order: localStorage first, since it reflects an explicit user choice, then the prefers-color-scheme media query as a fallback, then a default light theme if neither applies.

Getting the initial page load right matters more than the toggle button itself. Applying the theme class before the page renders prevents what's commonly called FOUC, a flash of unstyled or incorrectly themed content that briefly shows the wrong colors before JavaScript corrects it.

02Preventing the Flash of Wrong Theme

Callum's guide on DEV Community gets the ordering right: this inline script needs to sit at the very top of the head, executed as early as possible, before any CSS or content renders.

<script>
  document.documentElement.classList.toggle(
    'dark',
    localStorage.theme === 'dark' ||
    (!('theme' in localStorage) &&
      window.matchMedia('(prefers-color-scheme: dark)').matches)
  );
</script>

03The Toggle Button Function

Once the initial theme is set correctly, the toggle itself just needs to flip the class and save the new preference. whitep4nth3r's guide calls this the "preference cascade" in action, with the stored user preference always taking priority once it exists.

function getInitialTheme() {
  const saved = localStorage.getItem('theme');
  if (saved) return saved;

  return window.matchMedia('(prefers-color-scheme: dark)').matches
    ? 'dark'
    : 'light';
}

function applyTheme(theme) {
  document.documentElement.classList.toggle('dark', theme === 'dark');
  localStorage.setItem('theme', theme);
}

// Set initial theme on page load
applyTheme(getInitialTheme());

// Wire up the toggle button
document.getElementById('theme-toggle').addEventListener('click', () => {
  const isDark = document.documentElement.classList.contains('dark');
  applyTheme(isDark ? 'light' : 'dark');
});

04Pairing the Toggle With CSS Custom Properties

The JavaScript only manages one class, all actual color values should live in CSS custom properties. This keeps the toggle logic simple and makes adding a third theme, or adjusting colors later, a CSS-only change.

:root {
  --bg-color: #ffffff;
  --text-color: #1a1a1a;
  --border-color: #e0e0e0;
  color-scheme: light dark;
}

html.dark {
  --bg-color: #1a1a1a;
  --text-color: #f0f0f0;
  --border-color: #3a3a3a;
}

body {
  background-color: var(--bg-color);
  color: var(--text-color);
  transition: background-color 0.2s ease, color 0.2s ease;
}

05Listening for Live OS Theme Changes

Some users switch their OS theme while your site is still open. Abbey Perini's guide covers listening for this properly, but only when the user hasn't explicitly overridden the setting themselves, otherwise a manual choice would get silently overwritten.

const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');

mediaQuery.addEventListener('change', (e) => {
  // Only respond to OS changes if the user hasn't set an explicit preference
  if (!localStorage.getItem('theme')) {
    applyTheme(e.matches ? 'dark' : 'light');
  }
});

💡 Quick Tip: test this behavior using Chrome DevTools' Rendering panel, which lets you emulate prefers-color-scheme without actually changing your OS settings, making it far faster to verify both branches of the logic.

06Storage Approach Comparison

A quick reference for the different ways to persist a theme preference.

07Implementation Checklist

A short list to confirm before shipping a dark mode toggle to production.

08Common Questions