CSS color-scheme Property

The color-scheme property tells the browser which color modes your design supports so it can adjust native UI elements like scrollbars and form controls to match.

selector { color-scheme: normal | light | dark | light dark; }
normal The element is not aware of color schemes and should be rendered using the browser's default internal styles.
light The element indicates it can be rendered using the operating system's light color scheme.
dark The element indicates it can be rendered using the operating system's dark color scheme.
light dark The element supports both light and dark modes and will switch based on the user's system preferences.
only <keyword> Forces the browser to stick to a specific scheme and prevents it from overriding the colors for that element.

Code Examples

This basic example tells the browser the document supports both modes and uses a media query to adjust custom colors while the browser handles UI elements.

:root {
  color-scheme: light dark;
  background-color: #ffffff;
  color: #111111;
}

@media (prefers-color-scheme: dark) {
  :root {
    background-color: #111111;
    color: #ffffff;
  }
}

This advanced example uses JavaScript to toggle a dark mode class and updates the color-scheme property dynamically to keep the browser UI in sync.

<style>
  :root { color-scheme: light; }
  :root.dark-theme { color-scheme: dark; }
  body { background-color: #ffffff; color: #222222; }
  .dark-theme body { background-color: #222222; color: #ffffff; }
</style>
<button id="themeBtn">Toggle Theme</button>
<script>
  const btn = document.getElementById("themeBtn");
  btn.onclick = () => {
    const isDark = document.documentElement.classList.toggle("dark-theme");
    document.documentElement.style.colorScheme = isDark ? "dark" : "light";
    console.log("The hex code for the dark background is " + "#222222");
  };
</script>

Pro Tip

If you want to force a specific part of your page to stay light or dark regardless of system settings, you can use the "only" keyword. For example, "color-scheme: only light;" tells the browser to never try and force a dark theme on that specific element, which is handy for sections of a page that must maintain a specific branding color regardless of the user's OS theme.

Deep Dive

Think of "color-scheme" as a handshake between your code and the browser. When you build a site with a dark background, the browser doesn't automatically know that. By setting this property, you're telling the browser's "User Agent" to flip the colors of things you don't usually control with CSS, like scrollbar tracks, select dropdowns, and form inputs. It ensures that the "native" parts of the browser don't stick out like a sore thumb against your custom design. It doesn't change your custom CSS colors, but it adjusts the default system-level rendering to match your intent.

Best Practices

Always apply "color-scheme" to the ":root" selector to ensure the entire document, including the viewport background and scrollbars, follows the same logic. Using the "light dark" value is the most flexible approach because it respects the user's operating system preferences automatically. This prevents the browser from rendering a bright white canvas while your heavy dark-mode CSS is still downloading, giving the user a smoother experience right from the start.

Common Pitfalls

A major point of confusion is thinking this property acts like a magic wand that transforms your whole site into dark mode. It doesn't. You still have to write the CSS for your own backgrounds and text. It only affects "User Agent" styles. Also, remember that since it is an inherited property, setting it on a parent will affect all children unless they have their own "color-scheme" value defined.

Accessibility

Properly setting "color-scheme" is a big win for accessibility. It prevents high-contrast UI elements like scrollbars from clashing with the page content, which can be distracting or physically uncomfortable for users with light sensitivity. It also ensures that system-generated form controls maintain enough contrast to be usable in both light and dark modes.

Dev Data Table: color-scheme property

default normal
animatable no
inherited yes
experimental no
year_intro 2020
year_standard 2022
js_syntax_1 document.documentElement.style.colorScheme = "dark";
js_syntax_2 document.documentElement.style.setProperty("color-scheme", "light dark");
js_note In JavaScript, use camelCase colorScheme for the style object or the standard hyphenated string when using the setProperty method.
browsers { "Chrome": 81, "Edge": 81, "Firefox": 96, "Safari": 13, "Opera": 68, "Chrome Android": 81, "Safari on iOS": 13, "Samsung Internet": 13, "Opera Mobile": 59 }
results render here...