CSS light-dark() Function

The CSS light-dark() function provides two color values and outputs one of them depending on whether the element is operating in a light or dark color scheme.

Introduced in CSS Color Module Level 5, light-dark() significantly streamlines styling for dark mode. Traditionally, supporting dark mode required duplicating style rules inside a @media (prefers-color-scheme: dark) media query. With light-dark(), both light and dark color values are defined together in a single declaration, and the browser automatically selects the appropriate color.

Syntax

The light-dark() function takes exactly two comma-separated colors:

Parameters

light-color: Any valid CSS <color> value used when the computed color-scheme is light.
dark-color: Any valid CSS <color> value used when the computed color-scheme is dark.

The `color-scheme` Requirement

For light-dark() to work, you must enable dark mode support on the element or an ancestor by setting the color-scheme property. By default, web pages have a color-scheme of normal, which causes browsers to only ever resolve the first (light) color.

To enable automatic switching based on the user's operating system preferences, set color-scheme: light dark on the root element:

Basic Examples

Here are some examples that demonstrate how to use light-dark():

Using `light-dark()` in Style Sheets

The CSS specifications state that you can use light-dark() wherever a CSS <color> value is accepted. For example, you can use light-dark() to set the colors of text, backgrounds, and borders:

Component-Level Scoping

Because light-dark() responds to the computed color-scheme of the element it applies to (rather than checking a global media query directly), you can override the color scheme for specific parts of a page:

In this example, any child elements inside .dark-sidebar that use light-dark() will automatically evaluate to their dark color values, regardless of whether the user has light mode or dark mode active at the operating system level.

`light-dark()` vs `@media (prefers-color-scheme)`

Here is how light-dark() compares with traditional dark mode media queries:

Feature	`light-dark()`	`@media (prefers-color-scheme)`
Syntax Placement	Both colors are specified together in a single CSS rule or custom property.	Requires duplicate rules or selectors wrapped inside a media query block.
Component-Level Overrides	Supported; can be controlled per element simply by changing `color-scheme`.	Difficult; media queries only check the system-level user preference.
Specification	CSS Color Module Level 5	Media Queries Level 5
Non-Color Styles	Only applies to color values.	Can change any CSS property (e.g. typography, layout, sizing).

Related Color Functions

color-mix(): Mixes two colors together by percentage in any color space.
oklch(): Perceptually uniform color function ideal for creating balanced light and dark mode palettes.
color(): Allows specifying colors in wide-gamut spaces like Display P3.

Browser Support

The following table provided by Caniuse.com shows the level of browser support for this feature.