Intent to ship: Sec-CH-Prefers-Color-Scheme client hint header

Skip to first unread message

François Beaufort 🇫🇷

Jun 7, 2021, 9:57:17 AM6/7/21
to blink-dev, Thomas Steiner

Contact emails,



API spec



The Sec-CH-Prefers-Color-Scheme client hint is modeled after the prefers-color-scheme user preference media feature as defined in Media Queries Level 5.

Blink component



CSS media queries, and specifically user preference media features like prefers-color-scheme, have a potentially significant impact on the amount of CSS that needs to be delivered by a page, and on the experience the user is going to have when the page loads.

It is a best practice to not load CSS for the particular non-matching color scheme in the critical rendering path, and instead to initially only load the currently relevant CSS. One way of doing so is via <link media>. However, high-traffic sites like Google Search that wish to honor user preference media features like prefers-color-scheme and that inline CSS for performance reasons, need to know about the preferred color scheme (or other user preference media features respectively) ideally at request time, so that the initial HTML payload already has the right CSS inlined.

TAG review 

TAG review status


Demo link


Developers can change the Sec-CH-Prefers-Color-Scheme client hint header value by emulating dark or light mode via DevTools in the Rendering panel.


The kClientHintsPrefersColorScheme WebFeature tracks Sec-CH-Prefers-Color-Scheme client hint usage.


Interoperability and Compatibility
There are no particular compatibility risks.

Interoperability is still pending on other browser vendors replying. Support for Client Hints in general is not enthusiastic though.

Signals from other implementations (Gecko, WebKit): 

Gecko: Pending (

WebKit: Pending (

Web / Framework developers: Positive (WICG proposal Issue: with feedback from developers working for Facebook and Magento. Twitter: The proposal was initially discussed in and received positive feedback via 16 Likes and 3 supportive comments:,, and




Developers will include Sec-CH-Prefers-Color-Scheme in the response headers Accept-CH and Critical-CH to let the browser know that they’re interested in the preferred color scheme. If supported, the request header Sec-CH-Prefers-Color-Scheme will be populated with the appropriate value.

Is this feature fully tested by web-platform-tests?


Tracking bug

Link to entry on the Chrome Platform Status 

Mike West

Jun 18, 2021, 2:54:51 AM6/18/21
to François Beaufort 🇫🇷, blink-dev, Thomas Steiner, Yoav Weiss
François, Thomas, Yoav, and I talked about this yesterday in light of some questions raised in the TAG review. Those questions seemed to me to be more related to Client Hints at large rather than this proposal specifically. Still, it's reasonable to work through them before shipping this, and it sounded like there was a clear path forward for that conversation.

While that's ongoing, I'm interested in the use cases for this hint specifically. Naively, it seems like color scheme preferences are only going to affect colors, and not substantial parts of layout. With that in mind, I wonder whether developers would be better served avoiding the complexity of client hints for this question, and relying on CSS variables and media queries instead (e.g. the suggestion in, with which I suspect you're familiar :) ). The marginal savings of avoiding a second set of color definitions don't seem substantial. How do y'all look at it?


You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to
To view this discussion on the web visit

Thomas Steiner

Jun 18, 2021, 3:07:57 AM6/18/21
to Mike West, François Beaufort 🇫🇷, blink-dev, Thomas Steiner, Yoav Weiss
Hi Mike,

Thanks for your time and wisdom during the meeting yesterday! 

In this particular case we're working together with Google Search, who have size-wise significant enough differences in the CSS they need to deliver for each color scheme paired with demands on page load time to justify the added complexity. We have heard similar arguments from Facebook. Additionally, pages want to avoid flashes of the wrong scheme, which you can observe on YouTube ( [screencast shared Google-internally, but the effect is easily reproducible externally]) and which this proposal would help avoid. Happy to go in more detail if need be.

Thomas Steiner, PhD—Developer Advocate (,

Google Germany GmbH, ABC-Str. 19, 20354 Hamburg, Germany
Geschäftsführer: Paul Manicle, Halimah DeLaine Prado
Registergericht und -nummer: Hamburg, HRB 86891

Version: GnuPG v2.1.23 (GNU/Linux)


Mike West

Jul 1, 2021, 2:22:57 PM7/1/21
to Thomas Steiner, François Beaufort 🇫🇷, blink-dev, Yoav Weiss

The TAG review raised security concerns that, after consultation with folks working on anti-abuse at Google, seem reasonably straightforward to deal with (and which need to be dealt with for the underlying media query in any event). I'm comfortable with that story, as well as the use cases presented.

That said, if the thread on the TAG review continues, and new or more specific concerns are raised, please surface them here and in our internal review thread.


Chris Harrelson

Jul 1, 2021, 3:07:40 PM7/1/21
to Mike West, Thomas Steiner, François Beaufort 🇫🇷, blink-dev, Yoav Weiss

Yoav Weiss

Jul 5, 2021, 1:16:35 AM7/5/21
to Chris Harrelson, Mike West, Thomas Steiner, François Beaufort 🇫🇷, blink-dev

Thomas Steiner

Jul 19, 2021, 11:49:22 AM7/19/21
to Yoav Weiss, Chris Harrelson, Mike West, Thomas Steiner, François Beaufort 🇫🇷, blink-dev
(Belated due to vacation) Thanks everyone for the approval and for working with us on improving and clarifying the proposal into its current state!
Reply all
Reply to author
0 new messages