prefers-color-scheme
Whether the OS or browser theme is light or dark.
In one line
Can tell whether your device theme is light or dark
Whether the OS or browser theme is light or dark.
Reveals the person's OS appearance setting (dark mode is used by an estimated 40 to 60% of mobile users) and time of day if auto switching. Low entropy; often set at the site by cookie.
What it can and can't do
What the user does: Nothing. It happens when the page loads.
It can
- Check whether you chose light or dark
- Show matching colors
- Ask for it in a request header, in Chrome, once the site opts in
It cannot
- See your wallpaper or other theme colors
- Change your theme
- Tell why you picked it
Browser support
| Browser | Status | First version | Released | Note |
|---|---|---|---|---|
| Chrome | Supported | 76 | 2019-07-30 | None |
| Edge | Supported | 79 | 2020-01-15 | None |
| Firefox | Supported | 67 | 2019-05-21 | None |
| Safari | Supported | 12.1 | 2019-03-25 | None |
| Safari on iPhone | Supported | 13 | 2019-09-19 | None |
| Chrome on Android | Supported | 76 | 2019-07-30 | None |
| Samsung Internet | Supported | 14.2 | 2021-06-25 | None |
How a site asks for it
| API | matchMedia('(prefers-color-scheme: dark)'); Sec-CH-Prefers-Color-Scheme |
| Browser compat keys | css.at-rules.media.prefers-color-scheme |
| How access is granted | none |
| What the user sees | None |
| Needs a secure context (HTTPS) | No |
| Needs a user gesture | No |
| How long it lasts | read fresh on every page load; nothing stored |
| How to take it back | none needed (no grant) |
| Inside an iframe | Readable from cross-origin iframes too (same values) |
Typical flow
- Page script reads the value
- No prompt is shown
Data you get
Shape: object
How often: static per session
| Field | Type | Unit | Range | Precision |
|---|---|---|---|---|
prefers-color-scheme | enum | None | light, dark | Not listed |
Technical limits
- Cannot tell automatic vs manual
The story
What it is
Tells a page whether your device is set to a light or dark theme.
For you
You never see the check, but you see the result. If your phone is in dark mode, many sites open dark without you doing a thing.
For makers
Matching dark mode makes a site feel polished and avoids a bright flash at night. It also leaks a tiny fact about you. Together with other signals it helps tell your devices apart.
Where you see it
| Type | Example | Apps |
|---|---|---|
| social | A social feed opens in dark colors in the evening because your phone is in dark mode. | Reddit, X |
| games | A browser game offers a dark menu that matches your system so it is easy on the eyes during late sessions. | None named |
| media | A news or reading site switches to light text on dark for night reading. | None named |
| productivity | A document or code editor switches theme when your system goes dark at sunset. | GitHub, Notion |
| ads | An advertiser serves a dark version of a banner so it does not glare against a dark page. | None named |
| analytics | A team sees that 60 percent of evening visitors use dark mode and tests a darker design. | None named |
| security | A fingerprint script adds the theme to a list of settings to help recognise a returning browser. | None named |
Risks
- Tiny fingerprint clue
- Reveals night habits
What the platform says
- web.dev: prefers-color-scheme. Google teaches sites to follow the system dark or light setting so pages feel native and ease eye strain.
- MDN: prefers-color-scheme. Documents the media feature that tells a page if the person wants a light or dark theme.
Good uses and abuse
Legitimate uses
- Respect OS theme and accessibility needs
- Adapt layout
Known abuse
- Infer disability or setting for fingerprinting
Scores
| Score | Value | Meaning |
|---|---|---|
| Sensitivity | 1 of 5 | How revealing the data is |
| Utility | 3 of 5 | How useful it is to honest apps |
| Friction | 0 of 5 | How much the user has to do |
| Fingerprint bits | 1 | Rough identifying entropy, when known |
History
- 2020-01, Firefox: RFP forces light
Related capabilities
Related
- Accessibility settings inferred. Can guess you may use accessibility settings by combining several browser signals
Sources
How well checked: Based on official documentation.