The CSS light-dark() Function

Modern websites are expected to support both light mode and dark mode. Users switch between themes depending on their environment, personal preference, or operating system settings. For years, developers relied on media queries, JavaScript, or complex theme variables to make this work.

Now CSS provides a cleaner solution with the light-dark() function.

What is light-dark()?

The light-dark() function allows you to define two values directly inside a CSS property.

The first value is used when the page is in light mode.

The second value is used when the page is in dark mode.

color: light-dark(#000, #fff);

In this example, the text becomes black in light mode and white in dark mode.

Instead of writing separate styles for each theme, everything can be defined in a single line.

Why Was It Introduced?

Before light-dark(), developers commonly used media queries.

.card {
  background: white;
  color: black;
}

@media (prefers-color-scheme: dark) {
  .card {
    background: #1a1a1a;
    color: white;
  }
}

While this works, it becomes difficult to maintain when a project grows. Every component may need its own dark mode overrides.

With light-dark(), the same styles can be written more compactly.

.card {
  background: light-dark(white, #1a1a1a);
  color: light-dark(black, white);
}

The result is easier to read and maintain.

Setting Up light-dark()

For the function to work correctly, the browser needs to know that your page supports both color schemes.

:root {
  color-scheme: light dark;
}

Without this declaration, the browser may not switch values as expected.

A complete example looks like this:

:root {
  color-scheme: light dark;
}

body {
  background: light-dark(#ffffff, #121212);
  color: light-dark(#222222, #f5f5f5);
}

The browser automatically chooses the appropriate value based on the active theme.

Using CSS Variables Together

The real power appears when light-dark() is combined with custom properties.

:root {
  color-scheme: light dark;

  --surface: light-dark(#ffffff, #1e1e1e);
  --text: light-dark(#222222, #f5f5f5);
  --border: light-dark(#dcdcdc, #444444);
}

Then components can simply use the variables.

.card {
  background: var(--surface);
  color: var(--text);
  border: 1px solid var(--border);
}

This creates a clean design system with minimal duplication.

Real World Example

Imagine a button that should adapt to the current theme.

.button {
  background: light-dark(#2563eb, #3b82f6);
  color: light-dark(white, white);
  border: 1px solid light-dark(#1d4ed8, #60a5fa);
}

The button automatically adjusts without additional theme specific styles.

Browser Support

The light-dark() function is supported in modern browsers including recent versions of Chrome, Edge, Safari, and Firefox.

If your audience uses up to date browsers, it is generally safe to use. For applications that must support older browsers, consider testing carefully or providing fallbacks.

Advantages of light-dark()

Less Code

Theme specific values can be defined directly where they are used.

Better Readability

Developers can immediately see both light and dark values in one place.

Easier Maintenance

No need to hunt through multiple media queries when updating colors.

Works Well With Design Systems

It integrates naturally with CSS variables and token based styling approaches.

Things to Keep in Mind

The function is designed primarily for values that change between light and dark themes. It should not replace all uses of media queries.

For example, if an entire layout changes based on screen size or theme, traditional media queries may still be the better choice.

Also remember that light-dark() depends on the color-scheme property being configured correctly.

Final Thoughts

The light-dark() function is one of those CSS features that feels surprisingly simple once you start using it. It reduces boilerplate, keeps theme related logic close to the styles that use it, and makes dark mode support much easier to maintain.

As browser support continues to improve, light-dark() is likely to become a standard part of modern CSS workflows. If you are building applications that support both light and dark themes, it is definitely worth adding to your toolkit.