Published on

The Definitive Guide to Dark/Light Mode Toggles with CSS Variables and JavaScript

Authors

'The Definitive Guide to Dark/Light Mode Toggles with CSS Variables and JavaScript'

Learn how to build a robust, persistent, and user-friendly dark/light mode toggle for your website from scratch using modern CSS Variables and vanilla JavaScript.

Table of Contents

The Definitive Guide to Dark/Light Mode Toggles with CSS Variables and JavaScript

In modern web development, user experience is king. And one of the most requested and appreciated features of the last few years is the ability to switch between a light and a dark theme. It’s more than just a trend; it's about accessibility, reducing eye strain in low-light environments, and even conserving battery life on OLED screens.

So, how do you build a dark mode toggle that's robust, remembers the user's choice, and respects their system preferences? The answer lies in a powerful combination of modern CSS and a sprinkle of JavaScript.

In this comprehensive guide, we'll walk you through everything, from the foundational concepts to advanced best practices. By the end, you'll be able to implement a professional-grade theme switcher on any website. Let's dive in!

Why This Approach is the Best

Before we get our hands dirty with code, let's talk about why this method is the industry standard:

  1. CSS Variables (Custom Properties): They allow us to define a palette of colors that can be reused throughout our stylesheet. Changing a theme becomes as simple as updating a few variable values, rather than overriding dozens of CSS rules.
  2. JavaScript: We use it for what it's best at—handling user interaction. It will listen for a click on our toggle and update the theme.
  3. localStorage: This browser feature lets us save the user's preference, so their chosen theme persists across page loads and browser sessions.
  4. prefers-color-scheme: This CSS media query provides a seamless initial experience by automatically selecting a theme based on the user's operating system setting.

This stack creates a fast, maintainable, and user-friendly solution.

Section 1: The Foundation - Structuring Your Colors with CSS Variables

The entire magic of this system begins with CSS Custom Properties, more commonly known as CSS Variables. If you're not familiar with them, they are entities defined by CSS authors which contain specific values to be reused throughout a document.

We define our theme colors as variables on the :root pseudo-class. This makes them available globally across our entire stylesheet. For our default (light) theme, it might look something like this:

/* styles.css */

:root {
  --font-color: #2c3e50;
  --bg-color: #ecf0f1;
  --card-bg-color: #ffffff;
  --header-bg-color: #bdc3c7;
  --primary-color: #3498db;
  --border-color: #bdc3c7;
}

/* Basic styling to demonstrate the variables */
body {
  background-color: var(--bg-color);
  color: var(--font-color);
  font-family: sans-serif;
  transition: background-color 0.3s, color 0.3s;
}

.header {
  background-color: var(--header-bg-color);
  padding: 1rem;
  text-align: center;
}

.card {
  background-color: var(--card-bg-color);
  border: 1px solid var(--border-color);
  border-radius: 8px;
  padding: 1.5rem;
  margin: 2rem auto;
  max-width: 600px;
  box-shadow: 0 4px 6px rgba(0,0,0,0.1);
}

.btn {
  background-color: var(--primary-color);
  color: #fff;
  border: none;
  padding: 0.8rem 1.2rem;
  border-radius: 5px;
  cursor: pointer;
}

Here, we've defined a set of semantic color variables like --bg-color and --font-color. Using var(--variable-name) we can apply these colors to our elements. The beauty of this is that if we want to change our primary color, we only need to update it in one place!

Section 2: Defining the Dark Theme

Now, how do we introduce the dark theme? We won't be creating a separate stylesheet. Instead, we'll use a data attribute on our <html> tag to signal which theme should be active. Let's choose data-theme="dark".

When this attribute is present, we'll simply redefine our CSS variables with their dark mode counterparts.

/* Add this to your styles.css */

[data-theme="dark"] {
  --font-color: #ecf0f1;
  --bg-color: #2c3e50;
  --card-bg-color: #34495e;
  --header-bg-color: #212f3c;
  --primary-color: #5dade2;
  --border-color: #566573;
}

That's it! With this CSS, any time the <html> element has the data-theme="dark" attribute, all our variables will instantly switch to their new values, and thanks to the cascading nature of CSS, our entire site's theme will change. The transition we added to the body element earlier will even animate the color changes smoothly.

Section 3: Building the Toggle with JavaScript

With our CSS structure in place, it's time to bring in JavaScript to handle the user interaction. Our goal is to add or remove the data-theme="dark" attribute from the <html> element when a button is clicked.

First, let's add a toggle button to our HTML:

<!-- index.html -->

<body>
  <header class="header">
    <h1>Theme Toggler Demo</h1>
    <button id="theme-toggle">Toggle Theme</button>
  </header>

  <main>
    <article class="card">
      <h2>Hello World!</h2>
      <p>This is a simple card component to demonstrate the theme switcher. Click the button in the header to see the magic happen.</p>
      <button class="btn">Click Me</button>
    </article>
  </main>

  <script src="app.js"></script>
</body>

Now, for the JavaScript (app.js):

// app.js

const themeToggle = document.getElementById('theme-toggle');
const htmlElement = document.documentElement; // Gets the <html> element

themeToggle.addEventListener('click', () => {
  // Check the current theme
  const currentTheme = htmlElement.getAttribute('data-theme');

  if (currentTheme === 'dark') {
    // Switch to light mode
    htmlElement.removeAttribute('data-theme');
  } else {
    // Switch to dark mode
    htmlElement.setAttribute('data-theme', 'dark');
  }
});

This script is straightforward:

  1. It grabs the toggle button and the <html> element.
  2. It adds a click listener to the button.
  3. When clicked, it checks if the data-theme attribute is currently 'dark'.
  4. If it is, it removes the attribute, reverting to the default light theme. Otherwise, it sets the attribute to 'dark'.

At this point, you have a fully functional, albeit basic, theme switcher!

Section 4: Persistence is Key - Remembering the User's Choice

There's a problem with our current setup. If you switch to dark mode and then refresh the page, it flashes back to light mode before settling. This happens because the browser has no memory of your choice.

Let's fix this with localStorage, a simple key-value storage in the browser that persists even after the tab is closed.

We'll modify our app.js to do two new things:

  1. On toggle: Save the chosen theme to localStorage.
  2. On page load: Check localStorage for a saved theme and apply it immediately.

Here's the updated JavaScript:

// app.js

const themeToggle = document.getElementById('theme-toggle');
const htmlElement = document.documentElement;

// Function to set the theme
const setTheme = (theme) => {
  if (theme === 'dark') {
    htmlElement.setAttribute('data-theme', 'dark');
    localStorage.setItem('theme', 'dark');
  } else {
    htmlElement.removeAttribute('data-theme');
    localStorage.setItem('theme', 'light');
  }
};

// Event listener for the toggle button
themeToggle.addEventListener('click', () => {
  const currentTheme = localStorage.getItem('theme') || 'light';
  const newTheme = currentTheme === 'dark' ? 'light' : 'dark';
  setTheme(newTheme);
});

// Apply the saved theme on initial load
const savedTheme = localStorage.getItem('theme');
if (savedTheme) {
  setTheme(savedTheme);
}

Now, when a user selects a theme, their choice is saved. The next time they visit your site, the savedTheme variable will retrieve their preference, and the setTheme function will apply it. No more resets!

Section 5: A Smarter Default - Respecting System Preferences

We can make our theme switcher even smarter. Most modern operating systems (Windows, macOS, iOS, Android) have a system-wide dark mode setting. We can detect this using the prefers-color-scheme CSS media query.

This allows us to provide an excellent default experience. If a user has their OS set to dark mode, our site will automatically load in dark mode for them the very first time they visit, even before they've touched our toggle.

The logic is as follows:

  1. Does the user have a preference saved in localStorage? If yes, use that.
  2. If not, does their system prefer dark mode? If yes, use dark mode.
  3. Otherwise, default to light mode.

Here's how we can implement this logic:

// app.js - A more robust version

const themeToggle = document.getElementById('theme-toggle');
const htmlElement = document.documentElement;

// Function to set the theme and update storage
const setTheme = (theme) => {
  htmlElement.setAttribute('data-theme', theme);
  localStorage.setItem('theme', theme);
  // Optional: Update toggle button text/icon here
  themeToggle.textContent = `Switch to ${theme === 'dark' ? 'Light' : 'Dark'} Mode`;
};

// Event listener for the toggle button
themeToggle.addEventListener('click', () => {
  const currentTheme = htmlElement.getAttribute('data-theme');
  const newTheme = currentTheme === 'dark' ? 'light' : 'dark';
  setTheme(newTheme);
});

// Function to determine and apply the initial theme
const applyInitialTheme = () => {
  const savedTheme = localStorage.getItem('theme');
  const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;

  if (savedTheme) {
    setTheme(savedTheme);
  } else if (prefersDark) {
    setTheme('dark');
  } else {
    setTheme('light'); // Default to light if no preference
  }
};

// Apply the initial theme when the script loads
applyInitialTheme();

We use window.matchMedia('(prefers-color-scheme: dark)').matches which returns true if the user's system preference is dark. Our logic now prioritizes a user's explicit choice (localStorage) over their system setting, which is the expected behavior.

Section 6: Best Practice - Eliminating the Flash of Incorrect Theme (FOUC)

We have one final, crucial problem to solve. If you followed along, you might notice a brief moment where the light theme is visible before the JavaScript kicks in to apply the dark theme. This is often called a FOUC (Flash of Unstyled Content) or, more accurately here, a Flash of Incorrect Theme.

This happens because our app.js script is likely deferred or loaded at the end of the <body>. The browser renders the default light theme first, and only then does our script run and switch to dark mode.

The solution is to run a tiny, blocking script in the <head> of your HTML. This script will apply the correct theme before the browser starts rendering the body content.

Here’s the inline script you should add to your index.html:

<!-- index.html -->

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Theme Toggler Demo</title>
  <link rel="stylesheet" href="styles.css">

  <!-- CRITICAL: Inline script to prevent FOUC -->
  <script>
    (function() {
      const theme = localStorage.getItem('theme');
      const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
      if (theme === 'dark' || (!theme && prefersDark)) {
        document.documentElement.setAttribute('data-theme', 'dark');
      }
    })();
  </script>
</head>
<body>
  <!-- ... your body content ... -->
  <script src="app.js"></script> 
</body>

Why this works:

  • It's placed in the <head>, so it executes before the <body> is rendered.
  • It contains no external dependencies and runs instantly ((function(){...})() is an IIFE).
  • It performs the exact same logic as our initial theme checker: check localStorage, then check prefers-color-scheme.
  • It sets the data-theme="dark" attribute on the <html> element immediately if needed.

By the time the browser renders the <body>, the correct data-theme attribute is already in place, and the CSS variables are correctly defined. The flash is completely eliminated!

Your main app.js file is still needed to handle the clicking of the toggle button, but the initial theme setting is now handled by this critical inline script.

Putting It All Together: The Final Code

Let's assemble the complete, production-ready solution.

index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>The Perfect Theme Toggle</title>
  <link rel="stylesheet" href="styles.css">

  <!-- Inline script to set initial theme and prevent FOUC -->
  <script>
    (function() {
      const theme = localStorage.getItem('theme');
      const systemPrefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
      
      if (theme === 'dark' || (!theme && systemPrefersDark)) {
        document.documentElement.setAttribute('data-theme', 'dark');
      }
    })();
  </script>
</head>
<body>

  <header class="header">
    <h1>The Perfect Theme Toggle</h1>
    <!-- A more semantic button -->
    <button id="theme-toggle" class="theme-toggle-btn" aria-label="toggle theme">
      Switch Theme
    </button>
  </header>

  <main>
    <article class="card">
      <h2>Welcome!</h2>
      <p>This implementation respects your choices. It remembers your last selection and even checks your OS preference on your first visit. The best part? No annoying flash of the wrong theme on page load.</p>
      <button class="btn">A Primary Button</button>
    </article>
  </main>

  <!-- This script handles the user interaction -->
  <script src="app.js"></script>
</body>
</html>

styles.css

:root {
  --font-color: #2c3e50;
  --bg-color: #ecf0f1;
  --card-bg-color: #ffffff;
  --header-bg-color: #bdc3c7;
  --primary-color: #3498db;
  --border-color: #bdc3c7;

  /* Add transition for smooth theme changes */
  --theme-transition-duration: 0.3s;
}

[data-theme="dark"] {
  --font-color: #ecf0f1;
  --bg-color: #2c3e50;
  --card-bg-color: #34495e;
  --header-bg-color: #212f3c;
  --primary-color: #5dade2;
  --border-color: #566573;
}

body {
  background-color: var(--bg-color);
  color: var(--font-color);
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
  transition: background-color var(--theme-transition-duration), color var(--theme-transition-duration);
  margin: 0;
  line-height: 1.6;
}

.header {
  background-color: var(--header-bg-color);
  padding: 1rem 2rem;
  display: flex;
  justify-content: space-between;
  align-items: center;
  transition: background-color var(--theme-transition-duration);
}

.header h1 {
  margin: 0;
  font-size: 1.5rem;
}

.card {
  background-color: var(--card-bg-color);
  border: 1px solid var(--border-color);
  border-radius: 8px;
  padding: 1.5rem;
  margin: 2rem auto;
  max-width: 600px;
  box-shadow: 0 4px 6px rgba(0,0,0,0.1);
  transition: background-color var(--theme-transition-duration), border-color var(--theme-transition-duration);
}

.btn, .theme-toggle-btn {
  background-color: var(--primary-color);
  color: #fff;
  border: none;
  padding: 0.8rem 1.2rem;
  border-radius: 5px;
  cursor: pointer;
  font-weight: bold;
  transition: background-color var(--theme-transition-duration);
}

.btn:hover, .theme-toggle-btn:hover {
  opacity: 0.9;
}

app.js

const themeToggleBtn = document.getElementById('theme-toggle');
const htmlElement = document.documentElement;

// This function now only handles the click logic and saving to localStorage
const toggleTheme = () => {
  const currentTheme = htmlElement.getAttribute('data-theme');
  // If data-theme is 'dark' or it's not set but system prefers dark, new theme is light
  const newTheme = currentTheme === 'dark' ? 'light' : 'dark';

  htmlElement.setAttribute('data-theme', newTheme);
  localStorage.setItem('theme', newTheme);
};

themeToggleBtn.addEventListener('click', toggleTheme);

// No need for initial theme setting here, it's handled by the inline script in <head>

Conclusion

You've done it! You now have a complete, professional, and robust dark/light mode toggle.

Let's recap the key principles that make this solution so effective:

  • CSS Variables provide a clean and maintainable way to manage theme colors.
  • A data-theme attribute acts as a simple, semantic switch for our CSS.
  • JavaScript handles the user interaction, making the toggle functional.
  • localStorage ensures the user's choice is remembered, providing a consistent experience.
  • prefers-color-scheme offers a smart, user-friendly default on their first visit.
  • An inline script in the <head> is the secret sauce to prevent the dreaded flash of incorrect theme, ensuring a polished and professional result.

Implementing a theme switcher is a fantastic way to enhance your projects and show your attention to user experience. Take this code, adapt it, and give your users the control they appreciate.

Happy coding!

Discuss on Twitter • View on GitHub