大网数据广告活动
Web 标准与前端开发

Sec-CH-Prefers-Color-Scheme header

· 52CE 我爱测

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 se

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 @media/prefers-color-scheme media query.

<table class="properties"> <tbody> <tr> <th scope="row">Header type</th> <td> Request header, <a href="/en-US/docs/Web/HTTP/Guides/Client_hints">Client hint</a> </td> </tr> <tr> <th scope="row">Forbidden request header</th> <td>Yes (<code>Sec-</code> prefix)</td> </tr> </tbody> </table>

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

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

Browser compatibility

See also

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。