color-scheme
You know how we have “dark mode” and “light mode” these days? Browsers also have “dark” and “light” color schemes baked into their default styles. The CSS color-scheme property lets the browser use (or choose) to display certain elements with its dark or light default styling.
The color-scheme property is defined in the CSS Color Adjustment Module Level 1 specification, where it is called the “Opting Into a Preferred Color Scheme” property. That’s a great name for it because setting it enables the browser’s light and dark color schemes to take effect when it recognizes a user’s system preferences. If the user prefers light, they get the browser’s light color scheme. Prefer dark? They get the dark color scheme instead. Think of it like providing the browser with a hint about the primary color of a page. If the primary color is light — such as a white background — then it’s best if an element’s default color has a darker contrast. If the primary color is dark , then the elements are better off with a lighter appearance. And once the browser gets the hint, it applies its corresponding color-scheme from its stylesheet automatically without us having to write additional styles or media queries. The CSS Color Adjustment Module Level 1 specification is currently in Editor’s Draft status at the time of writing. That means the feature could change between now and when the specification becomes a Candidate Recommendation. Browsers may implement the feature between then and now, but the feature is still considered experimental.
color-scheme: normal | [ light | dark | ]+ && only?- Initial value: normal
- Applies to: all elements and texts
- Inherited: yes
- Percentages: n/a
- Computed value: As specified
- Animation type: discrete
The color-scheme CSS property can be applied to the :root element so it is inherited globally, or it can be set on an individual element.
/* Keyword values */ color-scheme: normal; color-scheme: light; color-scheme: dark; color-scheme: light dark; color-scheme: dark light; color-scheme: only light; color-scheme: only dark; /* Global values */ color-scheme: inherit; color-scheme: initial; color-scheme: revert; color-scheme: revert-layer; color-scheme: unset;This value prevents an element from opting elements into the operating system’s light and dark color schemes. Instead, the browser’s default color scheme is used.
This can be used to reset an element’s inherited color scheme. Say you set color-scheme on the :root element:
All elements inherit that style. If we want a particular element to opt out of that style, that’s where normal relegates things back to the browser defaults.
This value opts elements into the operating system’s light color scheme.
This value opts elements into the operating system’s dark color scheme.
This value is used alongside either the light or dark value:
When we do that, we’re telling the browser to opt an element into only the light color scheme, or only the dark. So, if we set color-scheme: only light on an element, that element can receive the operating system’s light color scheme, but cannot use its dark color scheme… and vice versa.
Opting into light and dark color schemes at the same time
/* Light and dark color schemes are supported, but `light` is my preferred option. */ :root
Notice that the order matters. So, even though an element is opted into both color schemes, the first is what gets first preference. Setting both values on the :root is a good way to make sure all of your elements support color schemes, while leaning into one over the other.
The exact colors are up to the browser
Browsers include their own stylesheets. We call these User Agent (which is just a fancy word for “browser”) styles. Let’s peek at one of the CSS in WebKit’s stylesheet:
See that -webkit-link color? That’s a named color only WebKit recognizes and it applies that color to all links by default, unless we override it with our own CSS. So, when a rendering engine like WebKit sees that we’ve set color-scheme: light or color-scheme: dark on an element, it decides which version of that color will work best for the situation.
Light and dark color schemes are not specific color palettes. For example, a stark black-on-white scheme and a sepia dark-on-tan scheme would both be considered light color schemes. To ensure particular foreground or background colors, they need to be specified explicitly.
But sometimes the color is up to the user
Operating systems often allow users to override its system colors with a preferred color scheme.
These are the preferences a browser checks when it sees color-scheme declared on an element. If the user selects a color from these preferences, then the browser’s default styles will respect those operating system settings.
There’s a corresponding tag, too
We can get the same benefits by adding the tag to the in the HTML of a webpage:
There’s no need to specify the color scheme in both the HTML and CSS, but it could be handy in situations where your stylesheet fails to load for some reason. That way, the page is still opted into both color schemes, even if the CSS is unavailable.
If you’re trying to choose between the HTML meta tag and the CSS property, you might lean toward the HTML. HTML is instantly available. The CSS method, on the other hand, requires the stylesheet to download before it applies the property and the time it takes to do that could result in a slight flash of incorrect color theme.
color-scheme is all about default appearances
So, elements on a page that have default colors from the User Agent stylesheet — like the background-color of form controls and the color of text — update according to the color-scheme value. Apple explains this nicely it’s “Supporting Dark Mode in Your Web Content” video:
[ color-scheme ] changes the default text and background colors of the page to match the current system appearance, standard form controls, scrollbars and other named system colors also change their look automatically.
We can see this with a quick and dirty demo where we’re only dealing with three elements:
- The document :root ,
- a element, and
- a
Notice that the demo does not set any color on the elements. I’ve set the :root to a light color scheme so that is what renders by default. Clicking the button set :root to dark .
See what changed when going from light to dark ?
- The document’s background-color changes from white to black.
- The Heading 1 color changes from black to white.
- The button’s color also changes from black to white.
- The button’s background-color changes shades
If we crack open DevTools, we can see that the Heading 1 color is coming from the User Agent stylesheet with a text value.
I’m honestly unsure what color text actually maps to. But if we move over to the Computed tab, we’ll see that it’s black ( rgb(0, 0, 0) ).
When we toggle the color-scheme property from light to dark , that computed value changes to white ( rgb(255, 255, 255) ):
Those colors were never set in the styles I wrote — they come from the browser’s stylesheet. And the color-scheme property is what controls them.
color-scheme is different than prefers-color-scheme
It’s easy to confuse the two. They take the same light and dark values afterall!
The difference? Again, color-scheme is all about default appearances. It tells the browser to update the colors in its stylesheet.
Meanwhile, prefers-color-scheme is all about applying the styles we write in our own stylesheet, and only when that condition is met. In other words, any style rules we write inside the media query are applied — it has nothing to do with the browser’s default styles.
Let’s revisit our last example where we changed the color-scheme of a page that contains the :root document, a heading, and a button. By default, I did not change any of the colors, but I did declare color-scheme: light . That means all of the colors are coming from the browser’s stylesheet.
…all of those default colors from the browser’s stylesheet changed. No media queries required!
Now let’s say we never declare color-scheme . We’d use the prefers-color-scheme media query to change those colors ourselves. Here’s an abbreviated example that changes the :root element’s background-color and color :
:root < background-color: white; color: black; >/* If user prefers a dark appearance */ @media (prefers-color-scheme: dark) < :root < background-color: black; color: white; >>The media query is only applied if the user’s operating system appearance is set to “Dark”.
If that condition matches, any styles we put in there are applied — we’re not limited only to the browser’s default colors and styles. For example, let’s change background-color and color to completely different colors when the prefers-color-scheme: dark :
Using color-scheme and prefers-color-scheme together
The truth is that it’s better to use the two together. Why? They do different things but complement each other nicely. We could create the most beautiful dark mode interface in the world using prefers-color-scheme , but some elements — like form controls and scrollbars — are outside our control without overriding a bunch of default browser styles. When we use the two together, we gain an easy way toi switch those defaults without the additional overhead.
Support for the CSS color-scheme property is pretty solid, as long as you’re using the light and dark values. Many browsers lack support for the only keyword at the time of writing, with Safari as the lone exception.
| Desktop Browsers | IE | Edge | Chrome | Firefox | Safari | Opera |
|---|---|---|---|---|---|---|
| color-scheme | No | 81+ | 81+ | 96+ | 13+ | 68+ |
| Keyword: only dark | No | No | No | No | 13+ | No |
| Keyword: only light | No | No | No | No | 13+ | No |
| Mobile Browsers | Safari iOS | Chrome Android | Firefox Android | Android Browser | Opera Mobile |
|---|---|---|---|---|---|
| color-scheme | 13+ | 108+ | 107+ | 108+ | 72+ |
| Keyword: only light | 13+ | No | No | No | No |
| Keyword: only dark | 13+ | No | No | No | No |
Source: Caniuse
color-scheme
The color-scheme CSS property allows an element to indicate which color schemes it can comfortably be rendered in.
Common choices for operating system color schemes are «light» and «dark», or «day mode» and «night mode». When a user selects one of these color schemes, the operating system makes adjustments to the user interface. This includes form controls, scrollbars, and the used values of CSS system colors.
Try it
Syntax
color-scheme: normal; color-scheme: light; color-scheme: dark; color-scheme: light dark; color-scheme: only light; /* Global values */ color-scheme: inherit; color-scheme: initial; color-scheme: revert; color-scheme: revert-layer; color-scheme: unset;
The color-scheme property’s value must be one of the following keywords.
Values
Indicates that the element isn’t aware of any color schemes, and so should be rendered using the browser’s default color scheme.
Indicates that the element can be rendered using the operating system light color scheme.
Indicates that the element can be rendered using the operating system dark color scheme.
Forbids the user agent from overriding the color scheme for the element.
Can be used to turn off color overrides caused by Chrome’s Auto Dark Theme, by applying color-scheme: only light; on a specific element or :root .
Formal definition
Formal syntax
Examples
Adapting to color schemes
To opt the entire page into the user’s color scheme preferences declare color-scheme on the :root element.
:root color-scheme: light dark; > Specifications
Browser compatibility
BCD tables only load in the browser
See also
- prefers-color-scheme media query to detect user preferences for color schemes.
- Applying color to HTML elements using CSS
- Other color-related properties: color , background-color , border-color , outline-color , text-decoration-color , text-emphasis-color , text-shadow , caret-color , and column-rule-color
- background-image
- print-color-adjust
Found a content problem with this page?
This page was last modified on Jul 17, 2023 by MDN contributors.
Your blueprint for a better internet.
MDN
Support
Our communities
Developers
Visit Mozilla Corporation’s not-for-profit parent, the Mozilla Foundation.
Portions of this content are ©1998– 2023 by individual mozilla.org contributors. Content available under a Creative Commons license.