Revisiting the perfect Dark Mode Switch in 2024

Direct link to this section#Challenges

For the perfect dark mode switch, the following challenges need to be considered:

• Avoid any reflows
• Avoid Flash of unstyled content (FOUC)
• Avoid duplicate CSS/SCSS code
• Avoid conflicts between prefers-color-scheme and selected value from switch

Requirements

The following requirements should be met regarding user events:

• on: initial page visit:
  • If a user prefers-color-scheme, this should be displayed.
  • If a user does not prefer a color-scheme, the default, i.e. 'light', should be displayed.
• on: dark mode switch change:
  • If a user interacts with the switch, it should display the color-scheme accordingly to the selected color-scheme from the switch (i.e. should override the prefers-color-scheme property).
• on: subsequent page visits:
  • If a user has interacted with the dark mode switch, the selected color-scheme should be displayed (i.e. should override the prefers-color-scheme property).
  • If a user has not interacted with the dark mode switch, it should fall back to the behaviour of the initial page visit.
• on: prefers-color-scheme change (while visiting the page):
  • If a user has interacted with the dark mode switch and changes prefers-color-scheme property (through system or user agent setting), the previously saved selection from switch must be discarded because it is no longer valid. The page should display the prefers-color-scheme accordingly.
  • If a user has not interacted with the dark mode switch and changes his system/browser-wide preference, the page should display the prefers-color-scheme accordingly.

Direct link to this section#The color-scheme CSS property

The color-scheme CSS property allows an element to indicate which color schemes it can comfortably be rendered in.

Here is a basic example of styling based on color schemes:

/*
 * The page supports both light and dark color schemes.
 */
:root {
  color-scheme: light dark;
}

/*
 * The page only supports light color scheme.
 */
:root {
  color-scheme: only light;
}

/*
 * The page only supports dark color scheme.
 */
:root {
  color-scheme: only dark;
}

Direct link to this section#The color-scheme meta tag

To aid user agents in rendering the page background with the desired color scheme immediately, a color-scheme value can also be provided in a <meta name="color-scheme"> element.

Taken from Standard metadata names:

This works at the document level in the same way that the CSS color-scheme property lets individual elements specify their preferred and accepted color schemes.

<!-- The page supports both light and dark color schemes. -->
<meta name="color-scheme" content="light dark" />

<!-- The page only supports light color scheme. -->
<meta name="color-scheme" content="only light" />

<!-- The page only supports dark color scheme. -->
<meta name="color-scheme" content="only dark" />

Direct link to this section#The prefers-color-scheme CSS property

The prefers-color-scheme CSS media feature is used to detect if a user has requested light or dark color themes (preference through an operating system or user agent).

This is just an example using both values. Sure this could be written shorter.

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

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

Direct link to this section#The color-scheme meta tag

The page supports both light and dark color schemes:

<meta name="color-scheme" content="light dark" />

Direct link to this section#Combining color-scheme and prefers-color-scheme

Since it is unfortunately not possible to overwrite prefers-color-scheme, we use a dataset property to work around. This approach eliminates the need for duplicate CSS/SCSS code completely.

And here is my missing piece of the puzzle from the MDN Web docs:

... the color-scheme property enables overriding a user's color scheme... Forcing ... to only use a light or dark color scheme can be done by setting the color-scheme property to light or dark.

<style>
  :root[data-theme='light'] {
    color-scheme: light;
    --color-bg: #fff;
    --color-text: #000;
  }

  :root[data-theme='dark'] {
    color-scheme: dark;
    --color-bg: #000;
    --color-text: #fff;
  }

  html {
    background-color: var(--color-bg);
    color: var(--color-text);
  }
</style>

This is hard to understand. Basically it means that color-scheme exclusively determines the default appearance, whereas prefers-color-scheme determines the stylable appearance.

Direct link to this section#Exploiting JavaScript's bad properties for profit

The <html> tag represents the root of an HTML document. To handle all the challenges, we define a dataset or data-attribute data-theme on the document root. Since we know that the default value of the theme will always be light, we can set this initially.

As the JavaScript and CSS code is critical, it must be inlined. There is no other option!

• User prefers-color-scheme=light or switched color-scheme=light, we do nothing.
• User prefers-color-scheme=dark or switched color-scheme=dark, we change the value.

Since we use data-theme on the documentElement and the inline JavaScript code is executed even before the painting of the <head> element starts, it is not possible for side effects such as reflow or FOUC to occur.

<html lang="en" data-theme="light">

<script>
  const root = document.documentElement
  const initialTheme = ('theme' in localStorage)
    ? localStorage.getItem('theme')
    : window.matchMedia('(prefers-color-scheme: dark)').matches
      ? 'dark'
      : 'light'

  if (initialTheme !== 'light') {
    root.setAttribute('data-theme', 'dark')
  }
</script>

<head>
<!--
It's ok. Please believe me.
https://html.spec.whatwg.org/multipage/semantics.html#the-html-element
-->
</head>

Direct link to this section#Adding Event Listeners

The final code adds the required event listeners on the DOMContentLoaded event.

The onClick event from the theme-toggle button will fire a callback when the user toggles the theme. We check the current color-scheme value, equivalent human readable: document.documentElement.style.colorScheme and set it to the opposite color-scheme accordingly. To persist the selection we store the selected value in the localStorage.

The change event from the window.matchMedia event will fire when the user toggles their system/user agent preference. The callback removes the persistent value from localStorage and changes the prefers-color-scheme accordingly.

<script>
  document.addEventListener("DOMContentLoaded", (event) => {
    document.getElementById('theme-toggle').addEventListener('click', () => {
      const nextTheme =
        (getComputedStyle(root).getPropertyValue('color-scheme') ===
          'light')
          ? 'dark'
          : 'light'
      localStorage.setItem('theme', nextTheme)
      root.setAttribute('data-theme', nextTheme)
    })

    window.matchMedia('(prefers-color-scheme: dark)').addEventListener(
      'change',
      (event) => {
        localStorage.removeItem('theme')
        root.setAttribute(
          'data-theme',
          event.matches ? 'dark' : 'light',
        )
      },
    )
  })
</script>