Dark and Light Mode with Custom Properties

The typical way of adding dark and light mode themes to a website is to add a class on the body that all of your styles can inherit. Using JavaScript, you toggle this class and even use localStorage to save the user's preferences. But with CSS custom properties and media queries, this process becomes much easier.

Custom Properties

If you're not familiar with custom properties (CSS variables), they allow us to store and reuse values in CSS dynamically. Unlike preprocessor variables (like Sass), CSS custom properties can be modified in real time and accessed via JavaScript.

Here’s a basic example:

:root {
  --background-color: white;
  --text-color: black;
}

body {
  background-color: var(--background-color);
  color: var(--text-color);
}

One of the biggest advantages of custom properties is their ability to be redefined at different levels of the CSS cascade. For example, inside an <article>:

article {
  --text-color: lightblue;
}

This means you can change the theme in a structured, maintainable way without rewriting large portions of your styles.

The prefers-color-scheme Media Query

Now that we understand custom properties, we can take advantage of the prefers-color-scheme media query. This query detects whether a user has set their system preference to light or dark mode and applies styles accordingly.

@media (prefers-color-scheme: dark) {
  :root {
    --background-color: black;
    --text-color: white;
  }
}

With this approach, users automatically get a dark theme if their system is set to dark mode—no JavaScript required.

Adding JavaScript for User Control

While the browser respects user preferences, we might still want to let users manually toggle themes and save their preference using localStorage.

1. Setting the Default Theme

To prevent a "flash" when switching themes, we move the theme-setting logic to the <head> so it executes before the page renders.

<script>
  (function () {
    const storedTheme = localStorage.getItem("theme");
    if (storedTheme) {
      document.documentElement.dataset.theme = storedTheme;
    } else {
      const prefersDark =
        window.matchMedia &&
        window.matchMedia("(prefers-color-scheme: dark)").matches;
      document.documentElement.dataset.theme = prefersDark ? "dark" : "light";
    }
  })();
</script>

2. Theme Toggle with Event Delegation

Instead of adding an event listener directly to the button, we use event delegation to improve performance and scalability.

document.addEventListener("click", (event) => {
  if (event.target.closest("#theme-toggle")) {
    const html = document.documentElement;
    const newTheme =
      document.documentElement.dataset.theme === "dark" ? "light" : "dark";
    html.dataset.theme = newTheme;
    localStorage.setItem("theme", newTheme);
  }
});

Applying the Theme in CSS

Now, we update our styles to reflect the JavaScript-controlled data-theme attribute:

[data-theme="dark"] {
  --background-color: black;
  --text-color: white;
}

[data-theme="light"] {
  --background-color: white;
  --text-color: black;
}

body {
  background-color: var(--background-color);
  color: var(--text-color);
}

No JavaScript? No Problem

Even if JavaScript is disabled, the prefers-color-scheme media query still applies the correct theme. The JavaScript layer only enhances the experience by giving users manual control.

This method is scalable and allows you to extend support for multiple themes beyond just dark and light. You could even introduce dynamic themes that change based on time of day!

By combining CSS variables, media queries, and JavaScript with event delegation and optimized loading, we get a clean and maintainable way to implement theme switching—without unnecessary complexity.