light-dark() Image Support

light-dark() Image Support

The light-dark() CSS function now works with image values, not just colors. You can switch between two images — photos, SVGs, illustrations — based on the active color scheme with a single CSS declaration.

.logo {
  content: light-dark(url("logo-light.svg"), url("logo-dark.svg"));
}

In light mode the first image is shown; in dark mode the second. No media query duplication, no JavaScript theme detection.

How It Works

light-dark() takes two values and returns the first when the computed color scheme is light, the second when dark. For images it accepts any <image> type:

/* URLs */
.icon {
  content: light-dark(url("icon-light.png"), url("icon-dark.png"));
}

/* Gradients */
.hero-bg {
  background-image: light-dark(
    linear-gradient(to bottom, #f0f0f0, #ffffff),
    linear-gradient(to bottom, #1a1a2e, #0f0f1a)
  );
}

Requires color-scheme

light-dark() only resolves correctly when color-scheme is set on the element or an ancestor:

:root {
  color-scheme: light dark; /* enables light-dark() on the whole page */
}

Without this, light-dark() resolves to its light value regardless of OS preference.

Replacing the Old Pattern

Before light-dark() image support, the pattern was a media query duplication:

/* Old */
.logo {
  content: url("logo-light.svg");
}

@media (prefers-color-scheme: dark) {
  .logo {
    content: url("logo-dark.svg");
  }
}

/* New */
:root {
  color-scheme: light dark;
}
.logo {
  content: light-dark(url("logo-light.svg"), url("logo-dark.svg"));
}

With background-image

:root {
  color-scheme: light dark;
}

.hero {
  background-image: light-dark(url("hero-light.webp"), url("hero-dark.webp"));
  background-size: cover;
}

With mask-image

.icon {
  mask-image: light-dark(url("mask-light.svg"), url("mask-dark.svg"));
  mask-size: contain;
}

Programmatic Theme Switching

When using a JS-toggled theme class, set color-scheme on :root to keep light-dark() in sync:

function setTheme(theme) {
  document.documentElement.style.colorScheme = theme; // "light" or "dark"
}

/* light-dark() reads the computed color-scheme automatically */
.avatar {
  content: light-dark(url("avatar-light.png"), url("avatar-dark.png"));
}

Browser Support

light-dark() for colors shipped in Chrome 123, Firefox 120, and Safari 17.5. Image support extends the same function — check @supports before relying on it in production:

@supports (content: light-dark(url("a"), url("b"))) {
  .logo {
    content: light-dark(url("logo-light.svg"), url("logo-dark.svg"));
  }
}

---