css-prefers-color-scheme

Use light and dark color schemes in all browsers

Usage no npm install needed!

<script type="module">
  import cssPrefersColorScheme from 'https://cdn.skypack.dev/css-prefers-color-scheme';
</script>

README

Prefers Color Scheme

NPM Version Build Status Discord

Prefers Color Scheme lets you use light and dark color schemes in all browsers, following the Media Queries specification.

'Can I use' table

Usage

From the command line, transform CSS files that use prefers-color-scheme media queries:

npx css-prefers-color-scheme SOURCE.css TRANSFORMED.css

Next, use that transformed CSS with this script:

<link rel="stylesheet" href="TRANSFORMED.css">
<script src="https://unpkg.com/css-prefers-color-scheme/dist/browser-global.js"></script>
<script>
colorScheme = initPrefersColorScheme('dark') // apply "dark" queries (you can change it afterward, too)
</script>

⚠️ Please use a versioned url, like this : https://unpkg.com/css-prefers-color-scheme@6.0.0/dist/browser-global.js Without the version, you might unexpectedly get a new major version of the library with breaking changes.

⚠️ If you were using an older version via a CDN, please update the entire url. The old URL will no longer work in a future release.

Usage

  • First, transform prefers-color-scheme queries using this PostCSS plugin.
  • Next, apply light and dark color schemes everywhere using this browser script.

How does it work?

This plugin used to work with color-index as detailed here : color-index. This is deprecated but will continue to work for now. color has better browser support and enables complex media queries.

Prefers Color Scheme uses a PostCSS plugin to transform prefers-color-scheme queries into color queries. This changes prefers-color-scheme: dark into (color: 48842621), prefers-color-scheme: light into (color: 70318723), and prefers-color-scheme: no-preference into (color: 22511989).

The frontend receives these color queries, which are understood in all major browsers going back to Internet Explorer 9. However, since browsers can only have a reasonably small number of bits per color, our color scheme values are ignored.

Prefers Color Scheme uses a browser script to change (color: 48842621) queries into (max-color: 48842621) in order to activate “dark mode” specific CSS, and it changes (color: 70318723) queries into (max-color: 48842621) to activate “light mode” specific CSS.

@media (color: 70318723) { /* prefers-color-scheme: light */
  body {
    background-color: white;
    color: black;
  }
}

Since these media queries are accessible to document.styleSheet, no CSS parsing is required.

Why does the fallback work this way?

The value of 48 is chosen for dark mode because it is the keycode for 0, the hexidecimal value of black. Likewise, 70 is chosen for light mode because it is the keycode for f, the hexidecimal value of white. These are suffixed with a random large number.