Dark Mode Bugs? Fix Native UI with color-scheme Property

Dark mode promises a cleaner, more comfortable browsing experience, but many implementations stumble over a subtle yet glaring issue: native user interface elements refusing to adapt. Scrollbars, dropdown menus, and form inputs remain stubbornly light-mode even when your custom dark theme is active. The root cause? Overlooking the color-scheme CSS property.

How OS-level preferences and manual toggles collide

Modern browsers respect the user’s operating system theme preference through the prefers-color-scheme media query. When enabled, it automatically applies dark or light styling to both custom and native elements. Developers can reinforce this behavior by declaring:

:root {
  color-scheme: light dark;
}

This single line instructs the browser to "honor the OS setting" for native controls like scrollbars and form elements. While elegant, this approach assumes users want their browser’s native appearance to dictate their experience.

The manual toggle trap

Many websites introduce a theme switcher to override the OS preference, adding a .dark class to the document root when toggled:

function toggleTheme() {
  document.documentElement.classList.toggle("dark");
  localStorage.setItem(
    "theme",
    document.documentElement.classList.contains("dark") ? "dark" : "light"
  );
}

CSS rules then apply custom dark styling:

:root.dark {
  --background: #121212;
  --text: #ffffff;
}

However, the color-scheme: light dark declaration at the root continues to defer to the OS, creating a mismatch. Native elements remain light, while the rest of the page turns dark—a jarring visual inconsistency.

Aligning native UI with your theme switcher

The solution is straightforward: remove the OS dependency when using a manual toggle. Replace the root color-scheme declaration with two targeted rules:

:root {
  color-scheme: light;
}

:root.dark {
  color-scheme: dark;
}

This ensures native controls inherit the same theme as your custom styles, eliminating the visual disconnect. The browser now respects the .dark class’s authority over both custom and native elements.

A case study: Fixing Memos’ dark mode scrollbar

The open-source note-taking app Memos encountered this issue in its dark mode implementation. Users reported white scrollbars against dark backgrounds, an obvious usability flaw. The development team traced the problem to a missing color-scheme update tied to the theme toggle.

They resolved it with a targeted JavaScript solution:

const isDarkTheme = (theme) => 
  theme.endsWith("-dark") || theme.endsWith(".dark");

document.documentElement.style.colorScheme = 
  isDarkTheme(theme) ? "dark" : "light";

For users on older versions, a browser script can dynamically sync the color-scheme property with the active theme:

(function() {
  const isDarkTheme = (theme) => 
    theme === "default-dark" || theme === "midnight";

  const updateColorScheme = (theme) => {
    document.documentElement.style.colorScheme = 
      isDarkTheme(theme) ? "dark" : "light";
  };

  const observer = new MutationObserver(() => 
    updateColorScheme(
      document.documentElement.getAttribute("data-theme")
    )
  );

  observer.observe(document.documentElement, { attributes: true });
  updateColorScheme(
    document.documentElement.getAttribute("data-theme")
  );
})();

This approach guarantees native UI elements mirror the selected theme.

To toggle or not to toggle?

Before implementing a manual theme switcher, consider its necessity. The combination of prefers-color-scheme and color-scheme: light dark offers a zero-JavaScript solution that works universally and respects user preferences without friction.

Ask whether your audience truly benefits from theme switching or if the feature risks over-engineering. Often, a well-implemented OS-aware dark mode delivers a smoother experience than a half-baked toggle. When simplicity aligns with functionality, everyone wins.