Skip to content
Tutorials Center
My learning

Topics

CSS Reference ยท Colors and Backgrounds

The color-scheme property

Reference for the CSS color-scheme property: declare light and dark support so form controls, scrollbars and system colors match, with examples and notes.

The color-scheme property tells the browser which color schemes an element can be displayed in: light, dark, or both. The browser then adjusts everything it draws itself, such as form controls, scrollbars, the default page background and text color, and the system color keywords like Canvas and CanvasText.

It does not restyle your own colors. If you set background: white yourself, that stays white. What the property does is make the parts you did not style follow the scheme, and it is the switch that the light-dark() function reads.

CSS
:root {
  color-scheme: light dark;
}

Try it

Light, dark and both

The panels use only system colors (Canvas, CanvasText, GrayText), so each one changes with its own color-scheme. The third panel follows your operating system or browser preference.

Pairing with light-dark()

Syntax

CSS
color-scheme: normal | [ light | dark | <custom-ident> ]+ && only?
  • Initial value: normal
  • Applies to: all elements
  • Inherited: yes
  • Animatable: no
  • Computed value: as specified

Values

Value Description
normal No scheme is declared. The element renders with the browser's light defaults (unless the page's embedder decides otherwise).
light The element supports a light scheme.
dark The element supports a dark scheme.
light dark Both are supported. The browser picks the one that matches the user's preference. Order does not matter for the result in practice.
only Added to a list such as light only. It stops the browser from forcing a dark appearance on the element, for example through an automatic dark mode feature.
<custom-ident> Other names are reserved for future schemes and are ignored today.

Usage notes

  • Set it on :root so the whole page, including the root scrollbar and the canvas background, follows the scheme. Because the property inherits, children pick it up automatically.
  • Use it with system colors and light-dark(). Colors like Canvas, CanvasText, Field and ButtonFace resolve differently per scheme, and light-dark(a, b) returns a in a light scheme and b in a dark one.
  • You can also declare it in HTML with <meta name="color-scheme" content="light dark"> in the <head>. The meta tag applies before the stylesheet loads, which avoids a white flash on dark systems.
  • Set it per component. color-scheme: dark on a single widget gives it dark form controls and scrollbars while the page stays light, which suits code panels and media players.
  • A scheme is a promise. If you declare dark, make sure your own colors still work in it. Mixing a hard-coded white background with dark controls looks broken.
  • prefers-color-scheme is different. That media query reads the user's preference; color-scheme states what your page supports. You normally use both together. See prefers-color-scheme.

Browser support

Supported in current versions of all major browsers and part of Baseline; check a compatibility table if you must support older releases.