Dark mode used to mean writing every colour twice: once in your normal rules and again inside a @media (prefers-color-scheme: dark) block. The CSS light-dark() function lets you write both values in one place. As of 13 November 2026, the modern.css Baseline tracker lists light-dark() as Baseline Widely Available, meaning it has worked across all major browsers for at least 30 months (MDN notes it has been available across browsers since May 2024). On the same day, text-wrap: balance also reached Widely Available.

For most teams, “widely available” is the signal that a feature is safe to use without a fallback. This tutorial shows how to build a light/dark theme with light-dark(), add a manual theme switcher, combine it with custom properties, and avoid a few common mistakes. Reference: MDN: light-dark().

The basics

light-dark() takes two colours. It returns the first when the element’s used colour scheme is light (or there’s no preference), and the second when it’s dark:

:root {
  color-scheme: light dark;
}

body {
  color: light-dark(#333b3c, #efefec);
  background-color: light-dark(#efedea, #223a2c);
}

The important part is color-scheme: light dark. Without it, light-dark() always picks the light value, because the element’s colour scheme is never dark. Setting it on :root also tells the browser to style its own UI (scrollbars, form controls, the default canvas) to match.

Before and after

The traditional approach:

:root {
  --bg: #ffffff;
  --text: #1a1a1a;
  --accent: #0057b8;
}

@media (prefers-color-scheme: dark) {
  :root {
    --bg: #121212;
    --text: #e8e8e8;
    --accent: #7ab7ff;
  }
}

With light-dark():

:root {
  color-scheme: light dark;
  --bg: light-dark(#ffffff, #121212);
  --text: light-dark(#1a1a1a, #e8e8e8);
  --accent: light-dark(#0057b8, #7ab7ff);
}

body {
  background: var(--bg);
  color: var(--text);
}

a {
  color: var(--accent);
}

Each token is defined once, with both values next to each other. That makes it much harder to add a new colour and forget its dark variant.

Adding a manual theme switcher

Many sites want three options: follow the system, force light, or force dark. Because light-dark() follows the element’s color-scheme, you only need to change that one property:

:root {
  color-scheme: light dark;          /* follow the OS */
}

:root[data-theme="light"] {
  color-scheme: light;               /* force light */
}

:root[data-theme="dark"] {
  color-scheme: dark;                /* force dark */
}
<label>
  Theme
  <select id="theme">
    <option value="system">System</option>
    <option value="light">Light</option>
    <option value="dark">Dark</option>
  </select>
</label>

<script>
  const root = document.documentElement;
  const select = document.getElementById("theme");
  const saved = localStorage.getItem("theme") || "system";

  function apply(value) {
    if (value === "system") root.removeAttribute("data-theme");
    else root.dataset.theme = value;
    localStorage.setItem("theme", value);
  }

  select.value = saved;
  apply(saved);
  select.addEventListener("change", (e) => apply(e.target.value));
</script>

No colours are duplicated anywhere. All your light-dark() values flip automatically when color-scheme changes.

To avoid a flash of the wrong theme on page load, put the small “read localStorage and set data-theme” part in an inline script in the <head>, before your stylesheet renders.

Theming just one section

color-scheme is inherited, so you can flip a single component. A dark promo banner on a light page:

.promo {
  color-scheme: dark;
  background: var(--bg);
  color: var(--text);
}

Everything inside .promo that uses your light-dark() tokens now resolves to the dark values, including native form controls.

Mixing with other modern colour features

light-dark() accepts any colour value, so it combines well with oklch() and color-mix():

:root {
  color-scheme: light dark;
  --brand: oklch(55% 0.18 255);
  --surface: light-dark(oklch(98% 0.01 255), oklch(22% 0.02 255));
  --border: light-dark(
    color-mix(in oklch, var(--brand) 20%, white),
    color-mix(in oklch, var(--brand) 35%, black)
  );
}

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

Check that each colour function you use is supported by your target browsers too. light-dark() being widely available doesn’t automatically make everything you put inside it widely available.

What about images?

MDN documents a second form of light-dark() that takes two images (for example two url() values or gradients). Be careful here: the Baseline tracker lists “light-dark() image values” as only Newly Available (since September 2026), not Widely Available. MDN’s page also notes that some parts of the feature vary in support. If you need wide support for image swaps, keep using a media query for now:

.logo {
  background-image: url("logo-light.svg");
}

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

For <img> elements, the <picture> element with a media="(prefers-color-scheme: dark)" source is another option, but note that it follows the OS setting, not your manual color-scheme switch.

Common mistakes

  1. Forgetting color-scheme. If dark values never show up, this is almost always why.
  2. Setting color-scheme: dark on :root only for the dark theme but forgetting that some third-party widgets read the scheme too. Test embedded components after switching.
  3. Checking contrast in only one mode. Run your contrast checks in both themes. Browser DevTools can emulate prefers-color-scheme so you can switch quickly.
  4. Using light-dark() for non-colour properties. It only works where a colour (or, in the newer form, an image) is expected. For spacing or font weight differences between themes, use a media query or a [data-theme] selector.

Bonus: text-wrap: balance is widely available too

The same tracker update marked text-wrap: balance as Widely Available. It evens out line lengths in short blocks of text, which stops headings from ending with a single lonely word:

h1, h2, h3, blockquote, figcaption {
  text-wrap: balance;
}

Browsers limit balancing to short text blocks for performance, so use it on headings and captions rather than long paragraphs.

Migration plan for an existing site

  1. Add color-scheme: light dark to :root.
  2. Convert each pair of light/dark custom properties into one light-dark() token.
  3. Delete the now-empty prefers-color-scheme colour blocks. Keep any that swap images.
  4. Add the data-theme overrides if you offer a manual switch.
  5. Test both themes, including forms, scrollbars and embedded widgets.

Key takeaways

  • light-dark() is Baseline Widely Available as of 13 November 2026, so the colour form is safe to use without fallbacks for most audiences.
  • It only works when color-scheme allows dark, so set color-scheme: light dark on :root.
  • A manual theme switcher becomes one property change: color-scheme.
  • The image form is newer, so keep media queries for image swaps if you need wide support.