The CSS color-scheme Property, Explained

The color-scheme CSS property tells the browser which color themes — light, dark, or both — a page or element is designed to support, so the browser can render its own native UI elements accordingly. It’s a small property with an outsized effect: without it, a page that switches to a dark theme can end up with light, browser-default scrollbars, checkboxes, and form fields sitting awkwardly on top of an otherwise dark design.

It’s easy to confuse with prefers-color-scheme and light-dark(), covered in our guide to CSS dark mode, but the three solve different parts of the same problem.

What it actually controls

color-scheme doesn’t style your own content — it doesn’t change the color of text or backgrounds you’ve written CSS for. It only affects elements the browser renders itself, using its own built-in styles:

• Form controls — checkboxes, radio buttons, <select> dropdowns, date pickers
• Scrollbars
• The default page background before any of your CSS applies
• Focus outlines and other native UI chrome

:root {
  color-scheme: light dark;
}

This tells the browser: “this page supports both light and dark presentation, so render your native UI elements in whichever the user currently prefers.” Without it, most browsers default every page to light, regardless of the user’s system preference — which is why a hand-built dark theme can still show a stark white date picker popup or a light-colored scrollbar.

color-scheme vs prefers-color-scheme vs light-dark()

These three pieces work together but do genuinely different jobs:

Feature	What it does
prefers-color-scheme	A media query — lets your CSS read the user’s OS-level theme preference and apply different rules
light-dark()	A CSS color function — picks between two colors for your own declared styles, based on the current scheme
color-scheme	A property — tells the browser which themes the page supports, so native UI renders correctly

prefers-color-scheme and light-dark() control the colors you write in your stylesheet. color-scheme controls the colors the browser draws on its own, outside your stylesheet entirely. A page can get the first two exactly right — a fully dark custom theme — and still have a jarring light-themed scrollbar or select dropdown if color-scheme was never set.

Setting it per element

color-scheme isn’t only a root-level property. It can be set on individual elements too, which matters for a component that intentionally breaks from the page’s overall theme:

:root {
  color-scheme: light dark;
}

.always-light-widget {
  color-scheme: light;
}

A widget embedded from a third party, or a section of a page deliberately kept light regardless of the site’s theme, can opt out of the page-wide setting this way — its native form controls and scrollbars stay light even if the rest of the page is rendering dark.

The meta tag equivalent

Before any of a page’s CSS has loaded, the browser still has to decide how to paint the initial background and chrome. For that earliest moment, there’s an HTML-level equivalent:

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

This is worth setting alongside the CSS property, not instead of it — the meta tag covers the brief window before stylesheets apply, avoiding a flash of light-themed browser UI on an otherwise dark page during the initial load, which the CSS property alone can’t prevent since it only takes effect once the CSS itself has been parsed and applied.

Why this is easy to miss

Most dark mode implementations focus entirely on the content people actually design: backgrounds, text, buttons, using custom properties as described in our piece on CSS custom properties. Native form controls are easy to overlook because they usually work fine without any CSS at all — until a dark theme makes their default light styling suddenly stand out. A <select> element with no styling applied inherits the operating system’s rendering, and that rendering follows color-scheme, not prefers-color-scheme used alone in your own stylesheet rules.

This also affects accessibility in a subtle way: a user with a system-wide dark mode preference who lands on a page that never sets color-scheme may see scrollbars and form fields that don’t match their expectations, even if the page’s own design otherwise respects prefers-reduced-motion and other user preferences carefully.

Browser support and the fallback behavior

color-scheme is well supported across current major browsers. Where it isn’t recognized, the behavior degrades safely: browsers that don’t understand the property simply ignore it and fall back to their default light rendering for native UI, exactly what would happen if the property were never set at all. There’s no risk of broken layout or a JavaScript error from including it — the worst case on an unsupported browser is the same light-scrollbar situation you’d have without the property.

That makes it a safe property to add unconditionally, without a feature-detection check or fallback branch: on a supporting browser, it fixes the mismatch; on a non-supporting one, it’s a no-op.

The takeaway

color-scheme closes the gap between a hand-built dark theme and the browser’s own native UI — form controls, scrollbars, default backgrounds — that your CSS never directly touches. Pair :root { color-scheme: light dark } with the equivalent meta tag for the earliest paint, and use prefers-color-scheme and light-dark() for the actual colors in your own styles. Skip it, and even a carefully built dark theme can end up with the one form control or scrollbar that never got the memo.