prefers-color-scheme media query
The prefers-color-scheme CSS media feature is used to detect if a user has requested light or dark color themes. A user indicates their preference through an operating system setting (e.g., light or dark mode) or a user agent setting.
Browser support
| Feature | Desktop | Mobile | ||||
|---|---|---|---|---|---|---|
| Chrome | Edge | Firefox | Safari | Chrome Android | Safari iOS | |
| 76 | 79 | 67 | 12.1 | 76 | 13 | |
| CSS at-rule | ||||||
prefers-color-scheme.respects-inherited-scheme Non-standard Respects `color-scheme` inherited from parent | 129 | 129 | 105 | | 129 | |
| Other | ||||||
http.headers.Sec-CH-Prefers-Color-Scheme Experimental The HTTP Sec-CH-Prefers-Color-Scheme request header is a media feature client hint which provides the user's preference for light or dark color themes. A user indicates their preference through an operating system setting (for example, light or dark mode) or a user agent setting. | 93 | 93 | | | 93 | |
- This browser only partially implements this feature
- This feature was removed in a later browser version (129)
- Only supports SVG images, not iframes.
- This browser only partially implements this feature
- This feature was removed in a later browser version (129)
- Only supports SVG images, not iframes.
- This browser only partially implements this feature
- This feature was removed in a later browser version (129)
- Only supports SVG images, not iframes.
Syntax
:root {
--bg: #ffffff;
--text: #1a1a1a;
}
@media (prefers-color-scheme: dark) {
:root {
--bg: #1a1a1a;
--text: #f0f0f0;
}
}
body {
background-color: var(--bg);
color: var(--text);
}Live demo
Use cases
-
System-aligned theming
Adapt page surfaces, text, and controls to the user’s preferred scheme without requiring an initial manual toggle.
-
Theme-aware components
Adjust reusable modules so they stay legible and coherent in both light and dark contexts.
Cautions
- Dark mode support should be complete enough that contrast, imagery, and focus states remain usable across the interface.
- System preference is a good default, but many products still benefit from a manual theme override as well.
Accessibility
- Theme preferences are part of accessibility for many users, so support should stay consistent rather than decorative only.