Setting color-scheme to use default dark mode values

I previously wrote about using prefers-color-scheme to make a dark mode version of your website. Recently, Chrome and Safari have added support for color-scheme, which allows you to use some browser defaults for dark mode. Where using prefers-color-scheme allows you to override your own CSS for users with a system dark mode enabled, this new option allows you to ask the browser to use some of its own default dark mode values.

How do I set color-scheme?

There are two ways to set it, either in your CSS or using a <meta> tag in your HTML.

Setting color-scheme in CSS

At the top of your CSS, add this:

:root {
  color-scheme: dark light;

Setting color-scheme in HTML

Add the following meta tag inside your <head> section:

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

Setting the color-scheme here can help avoid a flash of the wrong mode while waiting for the CSS file to load.

What values can I use for color-scheme?

You can set color-scheme to one of:

  • normal - Default value, implies light
  • dark - The site only supports dark mode
  • light - The site only supports light mode
  • dark light - The site supports both dark and light mode, with a preference for dark
  • light dark - The site supports both dark and light mode, with a preference for light

In the examples above, I’ve used dark light. This says that the website supports both dark and light modes. Putting dark first implies that it is the preferred option for the website. In practice, dark light and light dark are the same, because of how the browser chooses which mode to use.

The color-scheme spec specifies which value the browser should choose, based on the user’s preferences. It is written in such a way as to support more than two options in the future, but essentially it says to use the user’s preference where possible. The table below shows the various possibilities.

color-scheme User preference Result
normal light light
normal dark light
dark light light light
dark light dark dark
light dark light light
light dark dark dark
dark light dark
light light light

Note, if the user’s OS doesn’t support dark mode, or if they don’t have a preference, their implied preference is light.

What does setting color-scheme do?

Setting the colour scheme to dark in this way makes the browser change some of its default styling. Most noticeable in Chrome and Safari is that they change the default background colour to black, and set the text colour to white. You may also notice some changes to the styling of built-in elements, such as buttons, and radio and text inputs.

Which browsers support color-scheme?

The latest versions of both Chrome and Safari support setting color-scheme in both CSS and HTML. Firefox does not support it yet, and there is currently no release date for it.

Other recent posts: