The @container query, that elusive feature developers have been requesting
and proposing for years, has finally made its debut in a browser. Well, sort
of. Here we’ll explain what container queries are, how they work, and what
other features they might come with once fully supported in browsers.
Update :
🥳 Container queries have been available to use in all major browsers since
February 2023. We’ve updated the guide with changes and developments that have
happened since we first published.
New containment types have been added and other implied or planned
containment behavior has been adjusted or removed.
In the latest version of Chrome Canary,
the most recent @container query proposal is available for use behind an
experimental flag. Developed by OddBird’s own Miriam
Suzanne, the
draft builds upon the ideas
previously proposed by other web standards experts like David Baron, who wrote
the original
draft.
@Media queries sparked a responsive design revolution by allowing authors to
change the style of elements based on the size of the entire viewport. Up until
now, what could not be done was changing the style of an element based on the
size of one of its nearest containers.
The proposed @container query syntax feels a lot like writing a @media
query, but a main difference is that a @container query has to be implemented
in two parts.
In this demo (which only works in the latest version of Chrome
Canary), a blockquote is styled
differently depending on the size of its container.
Define a containment context
To achieve this, first define a containment context. This lets the browser know
which container to query against later and how exactly to query that specific
container.
article,
section {container-type: inline-size;}
The container-type[1] property turns on containment for the
selected elements, allowing for the testing of aspects such as style, size, and
state.
The inline-size value specifies that, in this case, queries will be made
against the containing element’s inline
axis.
Layout and
size[2] containment are applied automatically
as well.
(Block-size is also being considered as a containment type in the new
proposal. Inline-size seemed to satisfy more use-cases, so is being developed
first.)
Update :
Inline-size containment has been well-supported since container queries were
supported in stable versions of browsers.
Layout containment was previously applied automatically when
container-type and container-name properties were used. It has since been
removed from the container queries specification, but is still applied in some
browsers that have not updated their implementation of container queries.
Single-axis block-size containment proved to be impossible and has since
been abandoned.
The size containment type, which queries in both the inline and block axes,
has been available as a containment type in all browsers since February 2023.
Setting container-type: size allows for querying the container’s orientation
and aspect-ratio in addition to its size.
Now that a containment context has been defined, the @container rule is used
to tell the browser when and how styles should change inside each container.
With a narrow parent container, the blockquote features the image stacked on
top of the text.
The profile image sits on top of the quote in narrow containers.
At the first breakpoint, the layout for the blockquote changes so that the
profile image moves from being above the quote to sitting next to it, and the
text describing the speaker gets a heavier weight applied.
The profile image changes position at the first breakpoint to sit next to the quote.
/* change styles according to container size */@container(min-width: 35em){.quote {grid-gap: 1rem;grid-template:"media quote" auto/ max-content 1fr;}.media {align-items: center;}.source {font-weight: bold;}}
At the second breakpoint, the size of the text for the quote and the attribution
grows, the background changes color, and the overall shape of the blockquote
changes by way of a clip-path.
At a wider breakpoint, the blockquote gets a clip-path and a different background color.
Most Chromium based browsers added support for
scroll-state
containment in February of 2025. As of this update, it’s available in a
browser preview version of Opera.
Style queries – the ability to query a computed value of a containing element
– have been partially implemented by most browsers (no support in Firefox
yet). The current implementation allows for the querying of custom property
values:
@containerstyle(--theme: light){/* styles to apply here */}
Browsers are still working on adding support for using style queries to
evaluate booleans (@container style(gap) {...}) and property-value pairs
(@container style(display: flex) {...}).
Size queries have made it possible to now query a containing element’s
aspect-ratio and orientation.
Follow these steps to get started experimenting and making your own demos:
Download Chrome Canary or update to
the latest version.
Navigate to chrome://flags.
Search for “CSS container queries” and select Enabled.
Restart the browser.
The OddBird team would love to see what you come up with. Tag us on
Twitter with a link to whatever you create. In
the meantime, check out our collection of demos on
CodePen
for inspiration.
Syntax for establishing a containment context was updated
July 14, 2021 to use the new container-type and container-name
properties instead of contain.↩︎
A previous
version of this article listed style and layout as required values for the
contain property when establishing a containment context. These values are now
automatically applied when using the new container-type and container-name
properties. Updated July 14, 2021. ↩︎
The two values of the shorthand
were originally reversed, with container-type and then container-name.
Updated August 18, 2022.↩︎
position-area might be my favorite part of the CSS Anchor Positioning spec, with a ton of features packed in to make things just… work. But there’s no magic here, just a few key parts that work well.
For many years, it has been ‘best practice’ to use relative units (especially em and rem) for sizing text. That’s great! But after playing around with my user preferences, I think we can improve on the common approaches.
It is frustrating to track down why an anchor isn’t being found. I’ve found a simple way that should work in most cases. If that doesn’t work, step through the checklist, and then dive in to get a better understanding of how Anchor Positioning works.