The best light/dark mode theme toggle in JavaScript
Tags: webdev, css, javascript
Published: 2023-06-20 11:01:16

Learn how to build The Ultimate Theme Toggle™️ for your website using JavaScript, CSS custom properties, local storage and system settings. No framework required!
___

I used to disagree with light and dark mode toggles. “The toggle is the user system preferences!” I would exclaim naïvely, opting to let the [prefers-color-scheme CSS media query](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) control the theming on my personal website. No toggle. No choice. 🫠

I’ve been a dark mode user ever since it became a thing. But recently, I’ve preferred to use _**some**_ websites and tools in light mode — including my personal website — whilst keeping my system settings firmly in the dark. I needed a toggle. I needed a choice! And so does everyone else.

In this post I’ll show you how I built The Ultimate Theme Toggle™️ for my website in JavaScript that:

1. Stores and retrieves a theme preference in local browser storage,
1. Falls back to user system preferences,
1. Falls back to a default theme if none of the above are detected.

TL;DR: [here’s the code on CodePen](https://codepen.io/whitep4nth3r/pen/VwEqrQL).

## Add a data attribute to your HTML tag

On your HTML tag, add a data attribute such as `data-theme` and give it a default value of light or dark. In the past I’ve used the custom attribute `color-mode` instead of a data attribute (e.g. `color-mode="light"`). While this works, it’s not classed as valid HTML and I can’t find any documentation on it! Any insight on this is much appreciated. 😅

```html
<html lang="en" data-theme="light">
	<!-- all other HTML -->
</html>
```

## Configure theming via CSS custom properties

In your CSS, configure your theme colours via [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) (or variables) under each value for the `data-theme` attribute. Note that you don’t necessarily need to use `:root` in combination with `data-theme`, but it’s useful for global properties that don’t change with the theme (shown in the example below). [Learn more about the :root CSS pseudo-class on MDN.](https://developer.mozilla.org/en-US/docs/Web/CSS/:root)

```css
:root {
  --grid-unit: 1rem;
  --border-radius-base: 0.5rem;
}

[data-theme="light"] {
  --color-bg: #ffffff;
  --color-fg: #000000;
}

[data-theme="dark"] {
  --color-bg: #000000;
  --color-fg: #ffffff;
}

/* example use of CSS custom properties */
body {
  background-color: var(--color-bg);
  color: var(--color-fg);
}
```

Switch the `data-theme` attribute manually on your HTML tag, and you’ll see your theme change already (as long as you’re using those CSS properties to style your elements)!

## Build a toggle button in HTML

Add an HTML button to your website header, or wherever you need the theme toggle. Add a `data-theme-toggle` attribute (we’ll use this to target the button in JavaScript later), and an [aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) if you’re planning to use icons on your button (such as a sun and moon to represent light and dark mode respectively) so that screen readers and assistive technology can understand the purpose of the interactive button.

```html
<button
    type="button"
    data-theme-toggle
    aria-label="Change to light theme"
  >Change to light theme (or icon here)</button>
```

## Calculate theme setting on page load

Here’s where we’ll calculate the theme setting based on what I call the “_**preference cascade**_”.

### Get theme preference from local storage

We can use the [localStorage property in JavaScript](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) to save user preferences in a browser that persist between sessions (or until it is manually cleared). In The Ultimate Theme Toggle™️, the stored user preference is the most important setting, so we’ll look for that first.

On page load, use `localStorage.getItem("theme")` to check for a previously stored preference. Later in the post, we’ll update the theme value each time the toggle is pressed. If there’s no local storage value, the value will be `null`.

```javascript
// get theme on page load
localStorage.getItem("theme");

// set theme on button press
localStorage.setItem("theme", newTheme);
```

### Detect user system settings in JavaScript

If there’s no stored theme preference in `localStorage`, we’ll detect the user’s system settings using the [window.matchMedia() method](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia) by passing in a media query string. You’ll only need to calculate one setting for the purposes of the preference cascade, but the code below shows how you can detect light or dark system settings.

```javascript
const systemSettingDark = window.matchMedia("(prefers-color-scheme: dark)");
// or
const systemSettingLight = window.matchMedia("(prefers-color-scheme: light)");
```

`window.matchMedia()` returns a `MediaQueryList` containing the media query string you requested, and whether it `matches` (true/false) the user system settings.

```javascript
{
  matches: true,
  media: "(prefers-color-scheme: dark)",
  onchange: null
}
```

### Fall back to a default theme

Now you have access to a `localStorage` value and system settings via `window.matchMedia()`, you can calculate the preferred theme setting using the preference cascade (local storage, then system setting), and fall back to a default theme of your choice (which should be the default theme you specified on your HTML tag earlier).

We’ll run this code on page load to calculate the current theme setting.

```javascript
function calculateSettingAsThemeString({ localStorageTheme, systemSettingDark }) {
  if (localStorageTheme !== null) {
    return localStorageTheme;
  }

  if (systemSettingDark.matches) {
    return "dark";
  }

  return "light";
}

const localStorageTheme = localStorage.getItem("theme");
const systemSettingDark = window.matchMedia("(prefers-color-scheme: dark)");

let currentThemeSetting = calculateSettingAsThemeString({ localStorageTheme, systemSettingDark });
```

## Add an event listener to the toggle button

Next, we’ll set up an event listener to switch the theme when the button is pressed. Target the button in the DOM using the data attribute (`data-theme-toggle`) we added earlier, and add an [event listener](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener) to the button on click. The example below is quite verbose, and you might want to abstract out some of the functionality below into utility functions (which I’ve done in [the example on CodePen](https://codepen.io/whitep4nth3r/pen/VwEqrQL?editors=1112)). Let’s walk this through:

1. Calculate the new theme as a string
1. Calculate and update the button text (if you're using icons on your button, here's where you'll make the switch)
1. Update the aria-label on the button
1. Switch the data-theme attribute on the HTML tag
1. Save the new theme preference in local storage
1.  Update the currentThemeSetting in memory

```javascript
// target the button using the data attribute we added earlier
const button = document.querySelector("[data-theme-toggle]");

button.addEventListener("click", () => {
  const newTheme = currentThemeSetting === "dark" ? "light" : "dark";

  // update the button text
  const newCta = newTheme === "dark" ? "Change to light theme" : "Change to dark theme";
  button.innerText = newCta;  

  // use an aria-label if you are omitting text on the button
  // and using sun/moon icons, for example
  button.setAttribute("aria-label", newCta);

  // update theme attribute on HTML to switch theme in CSS
  document.querySelector("html").setAttribute("data-theme", newTheme);

  // update in local storage
  localStorage.setItem("theme", newTheme);

  // update the currentThemeSetting in memory
  currentThemeSetting = newTheme;
});
```

To confirm `localStorage` is being updated, open up your dev tools, navigate to the `Application` tab, expand `Local Storage` and select your site. You’ll see a key:value list; look for `theme` and click the button to watch it update in real time. Reload your page and you’ll see the theme preference preserved!

![Browser window with dev tools open on application tab. Local storage on whitepanther dot com is selected, showing a key value pair stored in the browser of theme light.](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/zosfts8gbby76vo1h40o.png)

## Put it all together!

You can now build your very own Ultimate Theme Toggle™️ by:

1. Using CSS custom properties to specify different theme colours, switched via a data attribute on your HTML tag
1. Using an HTML button to power the toggle
1.  Calculating the preferred theme on page load by using the preference cascade (local storage > system settings > fallback default theme)
1. Switching the theme on click of the toggle button, and storing the user preference in the browser for future visits

Here’s the full CodePen, and you can check out the working version on my personal website. Happy toggling!

{% codepen https://codepen.io/whitep4nth3r/pen/VwEqrQL %}