Sec-CH-Prefers-Color-Scheme header

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimental:This is anexperimental technology
Check theBrowser compatibility table carefully before using this in production.

Secure context: This feature is available only insecure contexts (HTTPS), in some or allsupporting browsers.

The HTTPSec-CH-Prefers-Color-Schemerequest header is amedia 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.

If a server signals to a client via theAccept-CH header that it acceptsSec-CH-Prefers-Color-Scheme, the client can then respond with this header to indicate the user's preference for a specific color scheme. The server can send the client appropriately adapted content including images or CSS to display a light or dark mode for subsequent rendered content.

This header is modeled on theprefers-color-scheme media query.

Header type	Request header,Client hint
Forbidden request header	Yes (`Sec-` prefix)

Usage notes

TheSec-CH-Prefers-Color-Scheme header allows sites to obtain user color scheme preference at request time; they could then choose to provide the relevant CSS for the user's preference inline, for performance reasons. If the server inlines the CSS, it might want to include aVary response header specifyingSec-CH-Prefers-Color-Scheme, to indicate that the response is tailored for a particular color scheme.

If performance is not a critical consideration in this context, you could instead handle the user's color scheme preference using theprefers-color-scheme media query, and/or theWindow.matchMedia() API.

Sec-CH-Prefers-Color-Scheme is a high entropy hint so the site needs to opt into receiving it by sending an appropriateAccept-CH response header. A user agent may intentionally omit theSec-CH-Prefers-Color-Scheme header to preserve user privacy since the user's preference could, in theory, be used for fingerprinting.

Syntax

http

Sec-CH-Prefers-Color-Scheme: <preference>

Directives

<preference>: A string indicating the user agent's preference for dark or light content:"light" or"dark".The value may originate from a corresponding setting in the underlying operating system.

Examples

Using Sec-CH-Prefers-Color-Scheme

The client makes an initial request to the server:

http

GET / HTTP/1.1Host: example.com

The server responds, telling the client viaAccept-CH that it acceptsSec-CH-Prefers-Color-Scheme. In this exampleCritical-CH is also used, indicating thatSec-CH-Prefers-Color-Scheme is considered acritical client hint.

http

HTTP/1.1 200 OKContent-Type: text/htmlAccept-CH: Sec-CH-Prefers-Color-SchemeVary: Sec-CH-Prefers-Color-SchemeCritical-CH: Sec-CH-Prefers-Color-Scheme

Note:We've also specifiedSec-CH-Prefers-Color-Scheme in theVary header to indicate that responses should be separately cached based on the value of this header (even if the URL stays the same).Each header listed in theCritical-CH header should also be present in theAccept-CH andVary headers.

The client automatically retries the request (due toCritical-CH being specified above), telling the server viaSec-CH-Prefers-Color-Scheme that it has a user preference for dark content:

http

GET / HTTP/1.1Host: example.comSec-CH-Prefers-Color-Scheme: "dark"

The client will include the header in subsequent requests in the current session, unless theAccept-CH changes in responses to indicate that it is no longer supported by the server.