Skip to Content
Platform.Ontology

prefers-color-scheme

Whether the OS or browser theme is light or dark.

Gets silentlyScreen and windowsCSS media featuresWeb browsersWhen the page loadsWhile you use it

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

BrowserStatusFirst versionReleasedNote
ChromeSupported762019-07-30None
EdgeSupported792020-01-15None
FirefoxSupported672019-05-21None
SafariSupported12.12019-03-25None
Safari on iPhoneSupported132019-09-19None
Chrome on AndroidSupported762019-07-30None
Samsung InternetSupported14.22021-06-25None

How a site asks for it

APImatchMedia('(prefers-color-scheme: dark)'); Sec-CH-Prefers-Color-Scheme
Browser compat keyscss.at-rules.media.prefers-color-scheme
How access is grantednone
What the user seesNone
Needs a secure context (HTTPS)No
Needs a user gestureNo
How long it lastsread fresh on every page load; nothing stored
How to take it backnone needed (no grant)
Inside an iframeReadable from cross-origin iframes too (same values)

Typical flow

  1. Page script reads the value
  2. No prompt is shown

Data you get

Shape: object
How often: static per session

FieldTypeUnitRangePrecision
prefers-color-schemeenumNonelight, darkNot 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

TypeExampleApps
socialA social feed opens in dark colors in the evening because your phone is in dark mode.Reddit, X
gamesA browser game offers a dark menu that matches your system so it is easy on the eyes during late sessions.None named
mediaA news or reading site switches to light text on dark for night reading.None named
productivityA document or code editor switches theme when your system goes dark at sunset.GitHub, Notion
adsAn advertiser serves a dark version of a banner so it does not glare against a dark page.None named
analyticsA team sees that 60 percent of evening visitors use dark mode and tests a darker design.None named
securityA 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

Good uses and abuse

Legitimate uses

  • Respect OS theme and accessibility needs
  • Adapt layout

Known abuse

  • Infer disability or setting for fingerprinting

Scores

ScoreValueMeaning
Sensitivity1 of 5How revealing the data is
Utility3 of 5How useful it is to honest apps
Friction0 of 5How much the user has to do
Fingerprint bits1Rough identifying entropy, when known

History

  • 2020-01, Firefox: RFP forces light

Sources

How well checked: Based on official documentation.

On this page