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
------


```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
--------

The client makes an initial request to the server:


```http
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
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:


```http
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 with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Client hints
* `prefers-color-scheme` CSS Media Query
* User-Agent Client Hints API
* Improving user privacy and developer experience with User-Agent Client Hints (developer.chrome.com)
* `Accept-CH`
* HTTP Caching > Varying responses and `Vary`