Firefox Tomorrow

http header

Sec-CH-Prefers-Color-Scheme header

View on MDN ↗

Limited availabilitySecure context

The HTTP Sec-CH-Prefers-Color-Scheme request header is a media 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 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](https://developer.mozilla.org/en-US/docs/Glossary/Request%20header), Client hint
[Forbidden request header](https://developer.mozilla.org/en-US/docs/Glossary/Forbidden%20request%20header) Yes (Sec- prefix)

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 @media/prefers-color-scheme media query, and/or the 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

Using Sec-CH-Prefers-Color-Scheme

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

SpecificationsStandards references are available on the canonical MDN page.

Browser compatibility

Browser compatibilityCompatibility data is available on the canonical MDN page.

See also