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:

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.