CSS color-scheme

The CSS color-scheme property allows a web author to indicate which color schemes an element can comfortably render in, such as light and dark modes.

Modern operating systems allow users to choose between light and dark appearances. When you specify color-scheme: light dark on a web page, you signal to the browser that your design accommodates both modes. In response, the browser automatically adapts native UI elements — including form controls (inputs, dropdowns, buttons), scrollbars, and system colors — to match the user's active system preference.

The color-scheme property is also the engine that powers the light-dark() function, enabling it to determine whether to output the light or dark color value.

What `color-scheme` Controls

Setting color-scheme automatically alters several default browser rendering behaviors:

Form Controls: Inputs, textareas, dropdowns, buttons, and date-pickers automatically render with dark backgrounds, dark borders, and light text when rendered under color-scheme: dark.
Scrollbars: Browser scrollbars for the viewport and scrollable elements switch to dark-themed tracks and thumbs.
System Colors: Standard CSS system colors like Canvas, CanvasText, and ButtonFace automatically resolve to their light or dark palette equivalents.
The light-dark() Function: Elements utilizing light-dark() resolve their colors according to the element's computed color-scheme.
Default Canvas: On the root element, color-scheme: dark renders the initial background of the page canvas in dark gray/black before custom styles are applied.

Syntax

Possible Values

normal: Indicates that the element does not support specific color schemes and should be rendered using the browser's default color scheme (typically light). This is the initial default value.
light: Indicates that the element supports and can be rendered in a light color scheme.
dark: Indicates that the element supports and can be rendered in a dark color scheme.
light dark: Specifies that the element supports both light and dark color schemes. The browser will choose whichever matches the user's operating system preference.
only light / only dark: The optional only keyword prevents the browser or operating system from applying forced dark mode overrides (such as browser-generated color inversions) to the element.

In addition, all CSS properties also accept the following CSS-wide keyword values as the sole component of their property value:

initial: Represents the value specified as the property's initial value.
inherit: Represents the computed value of the property on the element's parent.
unset: This value acts as either inherit or initial, depending on whether the property is inherited or not. In other words, it sets all properties to their parent value if they are inheritable or to their initial value if not inheritable.

Basic Property Information

Initial Value: normal
Applies To: All elements
Inherited?: Yes
Media: Visual
Animation Type: Not animatable (discrete)

Example Code

Working Example

<!DOCTYPE html>
<title>Example</title>
<style>
.demo-container {
  display: flex;
  gap: 20px;
  font-family: sans-serif;
  flex-wrap: wrap;
}
.scheme-box {
  flex: 1;
  min-width: 240px;
  padding: 16px;
  border-radius: 8px;
  border: 1px solid ##ccc;
}
.light-box {
  color-scheme: light;
  background-color: Canvas;
  color: CanvasText;
}
.dark-box {
  color-scheme: dark;
  background-color: Canvas;
  color: CanvasText;
}
.controls {
  display: flex;
  flex-direction: column;
  gap: 10px;
  margin-top: 12px;
}
</style>

<div class="demo-container">
  <div class="scheme-box light-box">
    <h3>color-scheme: light</h3>
    <div class="controls">
      <input type="text" value="Text input">
      <select>
        <option>Option 1</option>
        <option>Option 2</option>
      </select>
      <label><input type="checkbox" checked> Checkbox</label>
      <button type="button">Button</button>
    </div>
  </div>

<div class="scheme-box dark-box">
    <h3>color-scheme: dark</h3>
    <div class="controls">
      <input type="text" value="Text input">
      <select>
        <option>Option 1</option>
        <option>Option 2</option>
      </select>
      <label><input type="checkbox" checked> Checkbox</label>
      <button type="button">Button</button>
    </div>
  </div>
</div>

View Output Full Screen Preview

Component-Level Theming

Because color-scheme is inherited, you can easily create hybrid pages. For example, a website can be set to color-scheme: light overall, while specific sections (like a code editor, sidebar, or video player) can specify color-scheme: dark:

CSS Specifications

The color-scheme property is defined in CSS Color Adjustment Module Level 1 (W3C Candidate Recommendation Snapshot).

Browser Support

Browser support for CSS properties can vary, particularly for newer or experimental features. Check current browser compatibility before using a property in production, especially when supporting older browsers.

Initial Value

CSS properties have an initial value that applies when the property has not been explicitly set. The initial value is different from the value inherited from a parent element and may vary between properties.

Inheritance

Some CSS properties inherit their computed value from their parent element by default, while others do not. The inherit, initial, unset, and revert keywords can also be used to control how a property gets its value.

Vendor Prefixes

Most modern CSS properties use the standard, unprefixed syntax. Vendor-prefixed properties such as -webkit- are mainly relevant to older browser versions or specific features and should only be used when required by your browser support targets.