CSS Variables for Theme Switching

CSS custom properties (variables) defined on :root are globally available throughout the stylesheet. You define a complete color palette once — backgrounds, text colors, surfaces, borders — and reference them everywhere. This single source of truth makes theme switching trivial.

When a data-theme="dark" attribute is set on document.documentElement, a CSS selector like [data-theme='dark'] overrides the root variables with dark values. Components reference var(--color-bg) and automatically pick up the new values without any code changes.

At minimum, define: --color-bg (page background), --color-text (primary text), --color-primary (brand color), --color-surface (card/panel background), and --color-border (dividers). A consistent token set prevents ad-hoc color values from appearing in components.

In your component CSS, reference variables like background: var(--color-bg) and color: var(--color-text). You can also provide a fallback value: var(--color-bg, #ffffff). The browser resolves the variable at paint time, so a single class works for both light and dark themes.

Add transition: background-color 200ms, color 200ms to the :root selector. When the data-theme attribute changes, all elements that use CSS variables will animate to their new values simultaneously. This creates a polished feel without any JS animation code.

Managing theme via CSS variables is superior to setting inline styles from JavaScript. The browser handles all style recalculations natively, there are no extra React re-renders triggered for every themed child component, and the CSS cascade handles inheritance automatically. JS only needs to toggle one attribute on the root element.

You can combine CSS variables with the @media (prefers-color-scheme: dark) query as a CSS-only fallback. Define your dark overrides inside the media query in addition to (or instead of) the data-theme selector. This ensures dark mode works even if JavaScript has not run yet.

The most robust approach layers both mechanisms: the @media query provides the OS default, while a data-theme attribute allows user override via JavaScript. When the attribute is present it wins due to specificity; when absent, the media query takes effect.

For images that look poor on dark backgrounds, use the HTML picture element with a source media="(prefers-color-scheme: dark)" child. The browser selects the dark variant automatically. For SVG icons in CSS, you can use filter: invert(1) as a quick approximation.

CSS variables can also be scoped to individual components by defining them on a component root element rather than :root. This enables per-component theming, such as a sidebar with its own background token that differs from the page background, all still switching correctly with the global theme toggle.

Chrome DevTools shows resolved CSS variable values in the Styles panel. Click the variable reference to jump to its definition. This makes it easy to verify that the correct dark or light token is being applied to any element. You can also edit variable values live in the panel.

Which CSS selector is used to define global CSS custom properties that apply to the entire document?

CSS custom properties on :root provide a centralized token system for themes. Toggle a data-theme attribute on the html element to switch themes instantly. Add CSS transitions for smooth animation, use the prefers-color-scheme media query as a CSS-only fallback, and avoid per-component JS style overrides.