Repository navigation
[css-conditional-5] matchContainer() name may be confusing #14541
Description
element.matchContainer(query) evaluates query against the element's query container, i.e. its nearest eligible ancestor, not the element itself.
Regarding the naming, matchContainer() might suggest that you call it on the container itself rather than on a child of the container. I was also confused by that at first and left a comment on the issue, @lilles had the same reaction, and @lukewarlow mentioned being a bit worried about it too.
It's clearer to me now that I've spent more time with it (the "container" is the nearest ancestor that matches the query).
Some options we could consider:
- Keep as-is (container = matching ancestor element)
matchContainerQuery()matchContainer(query, { target: "self" | "ancestor" }), defaulting to"ancestor"so current behavior stays the same. Though I'm not sure it would actually reduce the confusion.matchAncestorContainer()- Other suggestions welcome
I slightly lean toward keeping matchContainer, since it's consistent with what "container" means in @container (the matching ancestor). Any thoughts?
Originally posted by @DevSDK in #13551 (comment)
For naming prior art, @emilio pointed out that Gecko has a devtools-only queryContainerFor(element) on CSSContainerRule, which returns the element's container.
Activity
Mention w3c#14541
lukewarlow commentedon Sep 30, 2026
From previous discussions I liked the idea of something like matchInsideContainer() or maybe hasContainer()?
The current name still feels wrong to me and I also do have use cases (such as the anchored container queries) for matching the container itself which is what matchContainer() sounds like to me.
LeaVerou commentedon Oct 16, 2026
There are two precedents here:
CSS.supports()andmatchMedia(). Given that we want not just current matching status but also to be notified of updates to it, the latter is the one to be consistent with.So, it has to be
matchContainer(), sadly. I don’t think it’s great, and we could have ended in a better place if we designed this properly from the start, but at this point the other proposed designs don’t cross the threshold of “this is so much better that it’s worth breaking consistency for”, see https://www.w3.org/TR/design-principles/#consistencyKilian commentedon Oct 16, 2026
matchContainermatches@container, which is in line withmatchMediamatching@media, so i'd be in favor of keeping itmatchContainer.Loirooriol commentedon Oct 16, 2026
Agree to keep
matchContainer. It's also not clear at all what would the behavior be if checking the condition on the element instead of its relevant container. E.g. if you are checkingblock-sizebut the element isn't a query container for container size queries, would it just track the size anyway like some kind ofResizeObserver, or would it just not work, or what?DevSDK commentedon Oct 19, 2026
I agree with @LeaVerou, @Kilian, and @Loirooriol. Given the
matchMedia()precedent, the alternatives don't seem better enough to justify breaking consistency.@lukewarlow Given that, would keeping
matchContainer()work for you?lukewarlow commentedon Oct 19, 2026
I won't block anything. It's something that MDN can try to point out in case anyone else gets caught by out by it.
DevSDK commentedon Oct 20, 2026
There appears to be enough support to propose an async resolution.
PROPOSED:
Keep the name matchContainer().astearns commentedon Nov 2, 2026
The CSSWG will automatically accept this resolution one week from now if no objections are raised here. Anyone can add an emoji to this comment to express support. If you do not support this resolution, please add a new comment.
Proposed Resolution: Keep the name matchContainer()