[mediaqueries] Effect of <meta name=color-scheme> on img and video sources

[JoshTumath]

Note

This was initially discussed in #10249 (comment)

@johannesodland has raised that, if the author sets <meta name=color-scheme content=dark>, it sets the document's used color scheme to dark, but there is no way for it to affect which HTML source element is selected based on the used color scheme.

An author might assume in this example that the HTML parser will select dark-mode-image.png to download, but it won't necessarily:

<!-- User has their color-scheme preference set to light mode. -->
<meta name="color-scheme" content="dark">

<picture>
  <source srcset="dark-mode-image.png" media="(prefers-color-scheme: dark)" />
  <img alt="" src="light-mode-image.png">
</picture>

There are two questions:

1. How could the UA choose a dark color scheme image to fetch based on the page's supported color schemes set by <meta name=color-scheme content=dark>?
2. How could the UA choose a dark color scheme image to fetch based on the used color scheme (which can be changed for all descendents in the DOM tree using the color-scheme CSS property)?

Both are difficult to solve because the HTML parser makes an immediate request for an image as soon as it identifies an image URL. When it encounters source elements in the picture element, it can only select a source using the information it has at parse time. At parse time, we do not know the used color scheme. The only thing we might know is the page's supported color schemes set by the <meta name="color-scheme"> tag.

Therefore, I think we are more concerned with solving Question 1. Both of these questions should be resolved in the HTML spec, but I think it's worth considering the CSSWG's thoughts, first.

Proposed solutions

Option 1. Propagate the page's supported color-scheme

Option 1a. propagate to prefers-color-scheme media query

Once the page's supported color scheme is parsed, when the HTML parser encounters a prefers-color-scheme media query in a source, it evaluates it using the page's supported color scheme. So in this example, it loads the dark-mode-image.png.

<meta name="color-scheme" content="dark">

<picture>
  <source srcset="dark-mode-image.png" media="(prefers-color-scheme: dark)" />
  <img alt="" src="light-mode-image.png">
</picture>

This solution doesn't introduce any new HTML syntax. Perhaps #7213 sets a precedent for this kind of behaviour?

Option 1b. propagate to a new media query document-color-scheme

@johannesodland suggests a new media query called document-color-scheme (or page-color-scheme) which gets the used colour scheme for the page determined from the.

<meta name="color-scheme" content="dark">

<picture>
  <source srcset="dark-mode-image.png" media="(document-color-scheme: dark)" />
  <img alt="" src="light-mode-image.png">
</picture>

Is it worth introducing a new media query for this use case? Would it be useful in a stylesheet, or would authors rather use @container color-scheme()?

Option 2. Create a new source element attribute to declare the color scheme

Introduce a new source attribute called colorscheme="light | dark".

Option 2a. Gets the used color scheme when lazy loaded

It only works if image lazy loading is set.

It specifies that the resource should only be loaded if the colour scheme matches the used color scheme.

<meta name="color-scheme" content="light">

<style>
div {
  color-scheme: dark;
}
</style>

<div>
  <picture>
    <source srcset="dark-mode-image.png" colorscheme="dark" />
    <img loading="lazy" alt="" src="light-mode-image.png">
  </picture>
</div>

Could it be confusing fro authors that it only works with lazy loading?

Option 2b. Like Option 2a, but gets the page color scheme when eagerly loaded

If lazy loading is set, it specifies that the resource should only be loaded if the colorscheme attribute matches the used color scheme.

If eager loading is set, it specifies that the resource should only be loaded if the colorscheme attribute matches an evaluation of the page's supported color scheme.

<meta name="color-scheme" content="dark">

<div>
  <picture>
    <source srcset="dark-mode-image.png" colorscheme="dark" />
    <img alt="" src="light-mode-image.png">
  </picture>
</div>

Could it be confusing for authors because it works very differently depending on whether using lazy loading?

Option 3. Create a new source element attribute for container queries

@romainmenke mentioned in #10249 (comment)

Relevant issue on conditionally loading resources based on container queries: whatwg/html#10182

whatwg/html#10182 proposes a container attribute for the source element. Theoretically, someone could use the color-scheme container query (from #10577 (comment)) to do the following:

<meta name="color-scheme" content="dark">

<picture>
  <source srcset="dark-mode-image.png" container="color-scheme(dark)" />
  <img loading="lazy" alt="" src="light-mode-image.png">
</picture>

Perhaps it would work similarly to Option 2a.

[lukewarlow]

Both are difficult to solve because the HTML parser makes an immediate request for an image as soon as it identifies an image URL. When it encounters source elements in the picture element, it can only select a source using the information it has at parse time.

So there's (at least) two possible solutions to this that works with any of the options you mention, the parser could just pick both image sources... then render the correct one once it's got information?

Alternatively, the HTML parser could make a best attempt at loading the right image based on the pages used color scheme, then when it gets to rendering if it realises actually this doesn't work (the subtree has a different color scheme) it can swap out for another source. This does potentially lead to double loads BUT at least its not unconditional double loads.

[SebastianZ]

This does potentially lead to double loads BUT at least its not unconditional double loads.

Double-loads should be avoided as far as possible. Or, it should at least be controllable by the user or the UA to reduce data transfer where necessary, e.g. in scenarios with low bandwidth or data transfers bound to costs.

Sebastian

[JoshTumath]

I've added Agenda+ on behalf of @johannesodland. I think issue will end up getting bounced to the WHATWG so that it's in the HTML spec, but I think it would be good to get the CSSWG's steer first.

[css-meeting-bot]

The CSS Working Group just discussed [mediaqueries] Effect of <meta name=color-scheme> on img and video sources, and agreed to the following:

• RESOLVED: (prefers-color-scheme) reflects <meta name=color-scheme>. Add (bikeshed-color-scheme) to always reflect the preference coming from the browser. (pending feedback from other commenters in the issue)

The full IRC log of that discussion

<emilio> TabAtkins: if you set `<meta name=color-scheme>` it changes the used color-scheme, but media queries don't affect it
<RRSAgent> I have made the request to generate https://www.w3.org/2026/03/31-css-minutes.html fantasai
<emilio> ... the `<picture>` lets you switch between multiple different sources based on media query
<emilio> ... if you have `<picture>` but `<meta name="color-scheme" content="dark">`, but os in light mode, prefers-color-scheme doesn't match
<emilio> TabAtkins: we could special-case picture / video to make their media query resolve differently (not in love)
<emilio> ... make media queries look into the meta
<emilio> ... or make sure that there's a way to use the used color-scheme of the video / picture
<emilio> q+
<emilio> ... but would require more interaction with HTML and not fix any existing light / dark mode picture
<emilio> ... thoughts?
<emilio> ... my proposal would be to make the media query use the meta color scheme
<emilio> ... I think it's the cleanest way to solve several of these
<emilio> ... other solutions would be great
<emilio> ... the current state is quite bad
<astearns> ack fantasai
<emilio> fantasai: alternative proposal, new `color-scheme` media query that reflects the document, so `prefers-color-scheme` reflects the user preferred color scheme
<florian> I think I like fantasai's proposal
<emilio> fantasai: so you can do your queries for the `color-scheme` without interacting with the preferred value
<TabAtkins> emilio: I dont' like that proposal. `prefers-color-scheme` already takes into account the embedder page; if your outer page is in light mode, an iframe will match (prefers-color-scheme: light)
<astearns> ack emilio
<TabAtkins> emilio: I don't like any of them too much, but I think Tab's is the least destructive
<fantasai> emilio: why would you mismatch?
<fantasai> TabAtkins: You might have a switcher on the page.
<fantasai> TabAtkins: Do that by setting the meta
<fantasai> emilio: Didn't we have scripted control thing?
<fantasai> TabAtkins: yes, but also, one page might be forced dark mode while you're using generic assets that are styled for both
<fantasai> emilio: This would only affect things in the markup, right?
<fantasai> emilio: For other things you'd use light-dark function
<fantasai> emilio: Feels a bit annoying in that preloading for picture resources, now would need to account for that.
<fantasai> emilio: E.g. parsing HTML speculatively, you assume that the media is going to match and now you need to account for the meta tag changing, which is a bit wasteful
<fantasai> TabAtkins: while potentially wasteful, it is avoiding loading the wrong resource
<astearns> s/avoiding loading/avoiding displaying/
<fantasai> TabAtkins: That would only be an issue if you changed the meta well after preload
<fantasai> emilio: Your scanner would need to account for the meta
<fantasai> TabAtkins: how does it interact with viewport meta's today?
<fantasai> emilio: It doesn't :)
<fantasai> emilio: It's explicitly bad because [something]
<TabAtkins> s/something/without the viewport meta, the viewport size depends on the content in some ways/
<fantasai> emilio: Any other meta tag other than device-width is realistically not common enough to optimize
<fantasai> emilio: tldr, I think Tab's proposal is the least bad but still eh
<astearns> ack fantasai
<emilio> fantasai: tabs and my proposal is effectively the same other than with other name right?
<emilio> emilio: yeah but I still think changing prefers-color-scheme is fine
<emilio> fantasai: there were some concerns about that
<emilio> ... we wouldn't have done the embedder thing if we had this
<emilio> emilio: but then prefers-color-scheme is pretty useless
<emilio> fantasai: you'd use prefers-color-scheme to set the initial switcher state or so
<emilio> ... we have several meta tags that are going to affect media queries, the viewport meta tag, the color-scheme, the text-scale which will also affect media queries
<florian> q+
<fantasai> emilio: Not sure I buy need for distinguishing color-scheme and prefers-color-scheme
<fantasai> emilio: prefers-color-scheme already responds to the embedding page color scheme
<fantasai> emilio: We need a different concept for this, because the used color scheme for lacking a meta tag is light.
<fantasai> emilio: even if that's not the preferred color scheme
<fantasai> emilio: Given how it's already not quite the user's preferred color scheme
<fantasai> emilio: I find it a bit more acceptable to re-use it.
<fantasai> emilio: If it wasn't influenced by the embeder page, then I could see the distiction being meaningful
<fantasai> emilio: but right now it's pretty arbitrary
<astearns> q+
<astearns> ack florian
<emilio> florian: I think I'd have a strong preference if we were in a clean slate
<TabAtkins> Just as a reminder, the only argument we had for (prefers-color-scheme) remaining unchanged is so that certain data-collection schemes can still tell what the user preferred even on pages with a <meta color-scheme> manually set
<emilio> ... the fact we're not I think I still lean towards fantasai's approach but less strongly
<emilio> ... if a page has mixed color-schemes
<emilio> ... let's say you have a "spec browser" with its own picker which sets the meta
<emilio> ... within that, the color-scheme media would respond to the meta, which ??
<emilio> ... specs have light and dark mode
<emilio> ... you might have a preference for that
<emilio> ... instead of viewing them and it's not in an iframe
<emilio> ... so you have a picker in the gallery but having access to the OS level preference would allow you to render the iframe in the right color scheme
<emilio> emilio: ah so you have an iframe and you want the "system" color scheme on the iframe
<emilio> florian: how locked in are we on the iframe thing?
<emilio> ... if we had a color-scheme media query, we could use _that_ for the iframe
<TabAtkins> emilio: so my problem with (color-scheme) is that, it's the MQ you want for everything in practice. We have all this code and examples already using (prefers-color-scheme)...
<TabAtkins> emilio: so when would you want the actual (prefers-color-scheme)?
<TabAtkins> emilio: I agree in an ideal world we'd have done (color-scheme) originally, but...
<fantasai> TabAtkins: The original argument for keeping them distinct was collecting user data
<fantasai> emilio: For Firefox browser UI we need this distinction
<fantasai> emilio: We need to use the user's preference for the UI
<fantasai> emilio: I added a new MQ with a different name for the UI vs the web content
<fantasai> emilio: Given massive amount of code using 'prefers-color-scheme' that would need to change
<fantasai> emilio: can we instead add a new MQ for the "system preferred scheme"?
<fantasai> florian: I think we do want both. Though naming whatever.
<fantasai> emilio: Internally we have concept of "used" and "preferred" color schemes
<fantasai> emilio: I don't have a great name... it's not really the system color scheme
<fantasai> emilio: Potentially 3 color schemes involved
<fantasai> emilio: 1. One that the page sets.
<fantasai> emilio: 2. One that the embedder sets.
<fantasai> emilio: 3. The browser's color scheme.
<fantasai> emilio: 4. OS color scheme.
<fantasai> ....
<fantasai> emilio: There's the top-level value that the browser sets for the top-level page.
<fantasai> emilio: Then there's the one that your embedder sets, e.g. on an iframe.
<fantasai> emilio: Then there's the one set by the iframe document itself.
<fantasai> emilio: We only have name for one of these
<fantasai> emilio: Least disruptive approach is introducing a new name for the one you most likely don't want to use.
<fantasai> astearns: Emilio, you're worried about compat because we already have documentation and use of prefers-color-scheme
<fantasai> astearns: If we follow Elika's proposal to introduce a new MQ, then content would need to move over to the new feature.
<miriam> q+
<fantasai> astearns: But if we follow Tab's proposal to re-interpret prefers-color-scheme, then we break existing behavior / uses.
<fantasai> astearns: With both ideas, we'd be changing the prefers-color-scheme in some way...
<fantasai> astearns: Maybe we can shift to better names for things?
<fantasai> emilio: Not sensible. A lot of SVG icons using prefers-color-scheme right now. Changing that beahvior would break things.
<astearns> ack astearns
<fantasai> emilio: With Tab's proposal, if you only have one <meta> value then the behavior changes, but only if you have one of them.
<fantasai> astearns: Then we're locked into not quite ideal name.
<astearns> ack miriam
<fantasai> miriam: One other use case, there are variations. Lighter light modes, and darker dark modes, and darker light mods, and lighter dark modes.
<fantasai> miriam: So reasonable to say that you're in a dark mode with a light mode preference, and combine these two preference to choose.
<fantasai> emilio: Maybe use ua-prefers-color-scheme or something?
<fantasai> emilio: And that gets you the top-level preference.
<fantasai> emilio: If there wasn't tons of existing content, Elika's suggestion is strictly better.
<fantasai> TabAtkins: Proposal: Go ahead and change the prefers-color-scheme on the top-level page to follow color-scheme meta value.
<fantasai> TabAtkins: Also add a new media query that only responds to the user's preference, ignoring anything the content does.
<fantasai> fantasai: So like prefers-color-scheme reflects the color scheme resolved via <meta color-scheme>, and user-color-scheme reflects the user preference always.
<TabAtkins> ua-prefers-color-scheme
<TabAtkins> (name technically TBD)
<fantasai> TabAtkins: And the JS API would not change the new one.
<florian> wfm
<fantasai> fantasai: Suggest we summarize the proposal into the issue, then resolve once we can cycle back to the people who had opinions.
<TabAtkins> PROPOSED: (prefers-color-scheme) reflects <meta name=color-scheme>. Add (bikeshed-color-scheme) to always reflect the preference coming from the browser.
<florian> +1
<TabAtkins> PROPOSED: (prefers-color-scheme) reflects <meta name=color-scheme>. Add (bikeshed-color-scheme) to always reflect the preference coming from the browser. (pending feedback from other commenters in the issue)
<TabAtkins> RESOLVED: (prefers-color-scheme) reflects <meta name=color-scheme>. Add (bikeshed-color-scheme) to always reflect the preference coming from the browser. (pending feedback from other commenters in the issue)
<iank_> are we doing any other issues today? or just republishing stuff?