Sec-CH-Prefers-Color-Scheme
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
The Sec-CH-Prefers-Color-Scheme
user preference media feature client hint request header 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 the Accept-CH
header that it accepts Sec-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 the prefers-color-scheme
media query.
Header type | Request header, Client hint |
---|---|
Forbidden header name | yes |
Usage notes
The Sec-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 a Vary
response header specifying Sec-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 the prefers-color-scheme
media query, and/or the Window.matchMedia()
API.
Sec-CH-Prefers-Color-Scheme
is a high entropy hint so the site needs to opt into receiving it by sending an appropriate Accept-CH
response header. A user agent may intentionally omit the Sec-CH-Prefers-Color-Scheme
header to preserve user privacy since the user's preference could, in theory, be used for fingerprinting.
Syntax
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
The client makes an initial request to the server:
GET / HTTP/1.1
Host: example.com
The server responds, telling the client via Accept-CH
that it accepts Sec-CH-Prefers-Color-Scheme
. In this example Critical-CH
is also used, indicating that Sec-CH-Prefers-Color-Scheme
is considered a critical client hint.
HTTP/1.1 200 OK
Content-Type: text/html
Accept-CH: Sec-CH-Prefers-Color-Scheme
Vary: Sec-CH-Prefers-Color-Scheme
Critical-CH: Sec-CH-Prefers-Color-Scheme
Note:
We've also specified Sec-CH-Prefers-Color-Scheme
in the Vary
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 the Critical-CH
header should also be present in the Accept-CH
and Vary
headers.
The client automatically retries the request (due to Critical-CH
being specified above), telling the server via Sec-CH-Prefers-Color-Scheme
that it has a user preference for dark content:
GET / HTTP/1.1
Host: example.com
Sec-CH-Prefers-Color-Scheme: "dark"
The client will include the header in subsequent requests in the current session, unless the Accept-CH
changes in responses to indicate that it is no longer supported by the server.
Specifications
Specification |
---|
User Preference Media Features Client Hints Headers # sec-ch-prefers-color-scheme |
Browser compatibility
BCD tables only load in the browser