Sec-CH-Prefers-Color-Scheme

The HTTP Sec-CH-Prefers-Color-Scheme request header is a client hint conveying the preferred color scheme for rendering content, allowing servers to deliver appropriately themed responses without requiring JavaScript.

Usage

The Sec-CH-Prefers-Color-Scheme header reports the same preference exposed by the CSS prefers-color-scheme media query. The preference originates from operating system settings (light mode or dark mode) or browser configuration. Servers receiving this hint send tailored HTML, CSS, and images matching the preferred theme, eliminating the flash of incorrect colors occurring when JavaScript detects and switches themes after page load.

Before a browser sends Sec-CH-Prefers-Color-Scheme, the server must opt in by listing the header in Accept-CH. Because the header carries high-entropy information, browsers require explicit permission before including the preference in requests. Sites serving different CSS or images based on color scheme must also list the header in Vary to ensure caches store separate versions for each theme.

The header is supported by Chromium-based browsers (Chrome, Edge, Opera) and requires a secure context (HTTPS).

Values

`"light"`

Indicates a preference for light color schemes with dark text on light backgrounds.

`"dark"`

Indicates a preference for dark color schemes with light text on dark backgrounds.

Example

A browser signals the operating system preference for dark mode. The server uses this information to deliver CSS optimized for dark themes, avoiding the need to load and discard light theme styles.

Sec-CH-Prefers-Color-Scheme: "dark"

A server marks Sec-CH-Prefers-Color-Scheme as critical using Critical-CH. The browser retries the initial request with the color scheme header attached, ensuring the first HTML payload already reflects the correct theme.

Accept-CH: Sec-CH-Prefers-Color-Scheme
Critical-CH: Sec-CH-Prefers-Color-Scheme
Vary: Sec-CH-Prefers-Color-Scheme

Takeaway

The Sec-CH-Prefers-Color-Scheme header delivers the preferred color scheme at request time, enabling servers to render the correct theme without relying on client-side JavaScript or causing visual flashes during page load.

See also

• User Preference Media Features Client Hints Headers (WICG)
• Client-Hints
• Accept-CH
• Critical-CH
• Vary
• HTTP headers