Dynamic Theme Switching with CSS

Why it exists

Modern operating systems allow users to set a system-wide preference for a light or dark appearance. Dynamic theme switching was created to allow websites and applications to respect this choice automatically, reducing user friction and improving accessibility, especially for users with light sensitivity.

The mental model

Think of your website asking the operating system, "Does this user prefer light or dark mode right now?" The OS answers, and your CSS automatically applies the correct "paint job" without any user interaction on your site. It’s like subscribing to a user's global appearance preference, ensuring your app feels integrated with their environment.

How it works

The core mechanism is the prefers-color-scheme CSS media feature. You first define your base styles, which typically act as the default (e.g., a light theme). Then, you create a media query block, @media (prefers-color-scheme: dark) { ... }, to override those styles for dark mode. Inside this block, you usually redefine CSS Custom Properties (variables) for colors, like --background-color or --text-color. The browser automatically applies these overrides when the user's OS setting is "dark". You can also detect this preference in JavaScript using window.matchMedia('(prefers-color-scheme: dark)') to dynamically change other assets, like chart colors or logos.

When to use it

Use this for any modern web application to provide a superior user experience. It is the standard for implementing light/dark modes and is expected by many users. It is especially valuable for content-heavy sites where users spend a lot of time reading, as offering a dark mode can reduce eye strain in low-light conditions.

When not to use it

Do not rely on this as the only way to switch themes. You should still provide an explicit in-app toggle. Some users may want your site in dark mode while their OS is light, or vice-versa. The media query should set the initial default, but a user's explicit choice should always override it. Also, avoid it if your brand identity is inextricably linked to a specific color scheme that doesn't translate well to a dark variant.

One canonical example

A common pattern uses CSS Custom Properties. First, define your default (light theme) colors in the :root selector: --bg-color: #FFFFFF; and --text-color: #333333;. Then, use a media query to redefine them for dark mode: @media (prefers-color-scheme: dark) { :root { --bg-color: #121212; --text-color: #E0E0E0; } }. Finally, apply these variables throughout your CSS, for example: body { background-color: var(--bg-color); color: var(--text-color); }.