prefers-color-scheme
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
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.