Big update!Introducing GitHub Bot Commands. Learn more
Log inBook a demo


Package Overview
File Explorer

Advanced tools


Use light and dark color schemes in all browsers


Version published
Weekly downloads
decreased by-9.98%

Weekly downloads



Prefers Color Scheme PostCSS Logo

npm version CSS Standard Status Build Status Discord

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

@media (prefers-color-scheme: dark) { :root { --site-bgcolor: #1b1b1b; --site-color: #fff; } } @media (prefers-color-scheme: light) { :root { --site-bgcolor: #fff; --site-color: #222; } } /* becomes */ @media (color: 48842621) { :root { --site-bgcolor: #1b1b1b; --site-color: #fff; } } @media (prefers-color-scheme: dark) { :root { --site-bgcolor: #1b1b1b; --site-color: #fff; } } @media (color: 70318723) { :root { --site-bgcolor: #fff; --site-color: #222; } } @media (prefers-color-scheme: light) { :root { --site-bgcolor: #fff; --site-color: #222; } }


Add Prefers Color Scheme to your project:

npm install postcss css-prefers-color-scheme --save-dev

Use it as a PostCSS plugin:

const postcss = require('postcss'); const prefersColorScheme = require('css-prefers-color-scheme'); postcss([ prefersColorScheme(/* pluginOptions */) ]).process(YOUR_CSS /*, processOptions */);

Prefers Color Scheme runs in all Node environments, with special instructions for:

NodePostCSS CLIWebpackCreate React AppGulpGrunt



The preserve option determines whether the original notation is preserved. By default, it is preserved.

prefersColorScheme({ preserve: false }) @media (prefers-color-scheme: dark) { :root { --site-bgcolor: #1b1b1b; --site-color: #fff; } } @media (prefers-color-scheme: light) { :root { --site-bgcolor: #fff; --site-color: #222; } } /* becomes */ @media (color: 48842621) { :root { --site-bgcolor: #1b1b1b; --site-color: #fff; } } @media (color: 70318723) { :root { --site-bgcolor: #fff; --site-color: #222; } }


// initialize prefersColorScheme (applies the current OS color scheme, if available) import prefersColorSchemeInit from 'css-prefers-color-scheme/browser'; const prefersColorScheme = prefersColorSchemeInit(); // apply "dark" queries (you can also apply "light") prefersColorScheme.scheme = 'dark';


<!-- When using a CDN url you will have to manually update the version number --> <script src="[email protected]/dist/browser-global.js"></script> <script>prefersColorSchemeInit()</script>

⚠️ Please use a versioned url, like this :[email protected]/dist/browser-global.js Without the version, you might unexpectedly get a new major version of the library with breaking changes.

Prefers Color Scheme works in all major browsers, including Safari 6+ and Internet Explorer 9+ without any additional polyfills.

To maintain compatibility with browsers supporting prefers-color-scheme, the library will remove prefers-color-scheme media queries in favor of cross-browser compatible color media queries. This ensures a seamless experience, even when JavaScript is unable to run.

Browser Usage

Use Prefers Color Scheme to activate your prefers-color-scheme queries:

import prefersColorSchemeInit from 'css-prefers-color-scheme/browser'; const prefersColorScheme = prefersColorSchemeInit();

By default, the current OS color scheme is applied if your browser supports it. Otherwise, the light color scheme is applied. You may override this by passing in a color scheme.

import prefersColorSchemeInit from 'css-prefers-color-scheme/browser'; const prefersColorScheme = prefersColorSchemeInit('dark');

The prefersColorScheme object returns the following properties — scheme, hasNativeSupport, onChange, and removeListener.


The scheme property returns the currently preferred color scheme, and it can be changed.

import prefersColorSchemeInit from 'css-prefers-color-scheme/browser'; const prefersColorScheme = prefersColorSchemeInit(); // log the preferred color scheme console.log(prefersColorScheme.scheme); // apply "dark" queries prefersColorScheme.scheme = 'dark';

The hasNativeSupport boolean represents whether prefers-color-scheme is supported by the browser.


The optional onChange function is run when the preferred color scheme is changed, either from the OS or manually.


The removeListener function removes the native prefers-color-scheme listener, which may or may not be applied, depending on your browser support. This is provided to give you complete control over plugin cleanup.


If styles are not applied you can enable debug mode to log exceptions.

import prefersColorSchemeInit from 'css-prefers-color-scheme/browser'; const prefersColorScheme = prefersColorSchemeInit('light', { debug: true }); <script src="[email protected]/dist/browser-global.js"></script> <script>prefersColorSchemeInit('light', { debug: true })</script>

Browser Dependencies

Web API's:

ECMA Script:

  • Object.defineProperty
  • Array.prototype.forEach
  • Array.prototype.indexOf
  • RegExp.prototype.exec
  • String.prototype.match
  • String.prototype.replace


⚠️ Applies to you if you load CSS from a different domain than the page.

In this case the CSS is treated as untrusted and will not be made available to the JavaScript polyfill. The polyfill will not work without applying the correct configuration for CORS.

Example :

pagecssCORS applies

You might see one of these error messages :

Chrome :

DOMException: Failed to read the 'cssRules' property from 'CSSStyleSheet': Cannot access rules

Safari :

SecurityError: Not allowed to access cross-origin stylesheet

Firefox :

DOMException: CSSStyleSheet.cssRules getter: Not allowed to access cross-origin stylesheet

To resolve CORS errors you need to take two steps :

  • add an HTTP header Access-Control-Allow-Origin: <your-value> when serving your CSS file.
  • add crossorigin="anonymous" to the <link rel="stylesheet"> tag for your CSS file.

In a node server setting the HTTP header might look like this :

// http://localhost:8080 is the domain of your page! res.setHeader('Access-Control-Allow-Origin', '');

You can also configure a wildcard but please be aware that this might be a security risk. It is better to only set the header for the domain you want to allow and only on the responses you want to allow.

HTML might look like this :

<link rel="stylesheet" href="" crossorigin="anonymous">

How does it work?

Prefers Color Scheme is a PostCSS plugin that transforms prefers-color-scheme queries into color queries. This changes prefers-color-scheme: dark into (color: 48842621) and prefers-color-scheme: light into (color: 70318723).

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.



What is css-prefers-color-scheme?

Use light and dark color schemes in all browsers

Is css-prefers-color-scheme popular?

The npm package css-prefers-color-scheme receives a total of 6,367,197 weekly downloads. As such, css-prefers-color-scheme popularity was classified as popular.

Is css-prefers-color-scheme well maintained?

We found that css-prefers-color-scheme demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.It has 2 open source maintainers collaborating on the project.

Last updated on 23 Aug 2022

Did you know?

Socket installs a Github app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.

Install Socket


Subscribe to our newsletter

Get open source security insights delivered straight into your inbox. Be the first to learn about new features and product updates.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc