HTTP Headers
Sec CH Prefers Color Scheme
HTTP Header
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 HTTP <code>Sec-CH-Prefers-Color-Scheme</code> 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 <code>Accept-CH</code> 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 <code>prefers-color-scheme</code> media query.
| Header type | Request header, Client hint |
|---|---|
| Forbidden request header | Yes (<code>Sec-</code> prefix) |
Syntax
Usage notes
The Sec-CH-Prefers-Color-Scheme header enables websites to obtain the user’s preferred color scheme during a request. This allows servers to inline CSS corresponding to the user’s preference directly within the response, improving performance. To ensure proper caching behavior when inlining CSS based on the user’s preference, the server can include a Vary response header specifying Sec-CH-Prefers-Color-Scheme, signaling that responses vary according to this header.
If performance is not an overriding concern, developers can alternatively handle the user’s color scheme preference using the prefers-color-scheme media query or the Window.matchMedia() API, offering more straightforward approaches.
Sec-CH-Prefers-Color-Scheme is considered a high-entropy hint, so servers must opt in to receive it by sending an Accept-CH response header. Users’ privacy is a priority; the user agent might deliberately omit this header to prevent fingerprinting based on their preference.
Examples
Using Sec-CH-Prefers-Color-Scheme
The initial request from the client to the server might look like this:
Request:
http
GET / HTTP/1.1
Host: example.comThe server responds, indicating it accepts the Sec-CH-Prefers-Color-Scheme header and also specifying critical client hints through Critical-CH. In addition, the server includes the Vary header for caching purposes:
http
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-SchemeNote: The Sec-CH-Prefers-Color-Scheme header is also included in the Vary header to ensure responses are cached separately based on the user’s preference. All headers listed in Critical-CH must also be present in Accept-CH and Vary.
Next, since Critical-CH is specified, the client will automatically retry the request and include the Sec-CH-Prefers-Color-Scheme header with the user’s preference, such as dark mode:
http
GET / HTTP/1.1
Host: example.com
Sec-CH-Prefers-Color-Scheme: "dark"In subsequent requests within the same session, the client will send this header unless the server indicates otherwise by removing Sec-CH-Prefers-Color-Scheme from the Accept-CH response header.
Directives
Sec-CH-Prefers-Color-Scheme: <preference>
Example
The <preference> directive specifies the user agent’s preferred appearance for content, indicating whether it favors a light or dark theme. The accepted values are "light" or "dark". This preference can be set based on the user’s system or application settings, allowing the content to adapt accordingly.
How to Modify Header using Requestly
Requestly is a powerful Chrome extension that allows you to modify HTTP headers, including the Sec-CH-Prefers-Color-Scheme header. This helps developers test how websites respond to different color scheme preferences such as light or dark mode. Steps to Modify the Sec-CH-Prefers-Color-Scheme Header:
- Install and open the Requestly Chrome extension. You can find it on the Chrome Web Store.
- Create a new rule: Click on “Create Rule” and choose “Modify Headers” from the list of available rule types.
- Add a new header modification:
- Under “Action”, select “Add” or “Override”.
- In the “Header Name” field, enter Sec-CH-Prefers-Color-Scheme.
- In the “Header Value” field, enter your preferred color scheme (e.g., dark or light).
- Set the URL condition: Specify the URL or pattern where this header change should apply (e.g., https://your-website.com/*).
- Save the rule.
Once configured, Requestly will add or modify the Sec-CH-Prefers-Color-Scheme header on matching requests, enabling you to simulate how your site handles different color scheme preferences for better design and accessibility testing.
You might need to modify this header to check how your website or application adapts to users’ light or dark mode settings. This makes it easier to ensure a smooth user experience across different themes without changing your device settings manually.
Table of Contents
- No headings found.
