prefers-color-scheme media query
The prefers-color-scheme media feature detects whether the user prefers a light or dark interface. It supports system-aligned theming and more respectful defaults.
Overview
The prefers-color-scheme media feature detects whether the user prefers a light or dark interface. It supports system-aligned theming and more respectful defaults.
Browser support
| Feature | Desktop | Mobile | ||||
|---|---|---|---|---|---|---|
| Chrome | Edge | Firefox | Safari | Chrome Android | Safari iOS | |
http.headers.Sec-CH-Prefers-Color-Scheme Experimental | 93 | 93 | | | 93 | |
| CSS at-rule | ||||||
| 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. | 76 | 79 | 67 | 12.1 | 76 | 13 |
prefers-color-scheme.respects-inherited-scheme Non-standard Respects `color-scheme` inherited from parent | 129 | 129 | 105 | | 129 | |
- 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.
Related links
Powered by web-features