Run this yourself. The measurement behind the two sections on cost and collapse:
css-container-query-cost/in the Coding Dunia code-examples repo. Headless Chromium, self-asserting, prints your machine's numbers.
CSS container queries are a layout feature that lets an element's styles respond to the size of its nearest containing element instead of the browser viewport, so a single component can adapt correctly no matter where it's placed on the page. Media queries check the viewport. CSS container queries check the container instead. This distinction is fundamental to building truly responsive, reusable components. Container queries (size type) are supported in all major browsers since Chrome 105, Safari 16, and Firefox 110 - overall support sits at around 93% as of early 2026.
Containment context is the term for the boundary a container query measures against - it's established by setting container-type on a parent element, and every @container rule inside that subtree resolves against that element's size rather than the viewport. Container query units, like cqi and cqw, are length units that resolve to a percentage of the nearest containment context's size instead of a percentage of the viewport.
What's Wrong with Media Queries for Component Design?
Imagine a Card component that looks great in a 3-column grid but breaks when placed in a sidebar. With media queries, you'd need to know the context at the component level - which defeats the purpose of encapsulation. According to MDN's containment documentation, a media query only ever has one piece of information available to it: the size of the viewport. It has no way to know whether the element it's styling sits in a 300px sidebar or a 1200px main column, so any component meant to be reused across contexts needs manual override classes for every placement.
Container queries solve this: the component adapts to wherever it's placed. The same Card markup, with zero JavaScript and zero variant classes, renders three or four visually distinct layouts depending purely on the pixel width of its parent.
A media query only ever knows the size of the browser viewport, never where an element actually sits on the page, which is why reusable components built around media queries always need manual override classes for every placement context. Container queries remove that dependency entirely by measuring the parent directly.
What Is the Basic Container Query Syntax?
/* 1. Define a containment context on the parent */
.card-wrapper {
container-type: inline-size;
/* Optionally name it */
container-name: card;
}
/* 2. Query the container inside the component */
@container (min-width: 400px) {
.card {
display: grid;
grid-template-columns: auto 1fr;
}
}
@container (min-width: 600px) {
.card {
gap: 2rem;
}
}
Named containers
Name containers when you have nested containment contexts:
.sidebar { container-type: inline-size; container-name: sidebar; }
.main { container-type: inline-size; container-name: main; }
@container sidebar (min-width: 300px) {
.widget { /* only applies when inside .sidebar */ }
}
@container main (min-width: 600px) {
.widget { /* only applies when inside .main */ }
}
How Do You Build a Truly Adaptive Card Component?
<div class="card-wrapper">
<article class="card">
<img class="card__image" src="..." alt="...">
<div class="card__body">
<h2 class="card__title">Article title</h2>
<p class="card__desc">Description text...</p>
<a class="card__cta">Read more</a>
</div>
</article>
</div>
.card-wrapper {
container-type: inline-size;
}
/* Mobile-first: stacked layout */
.card {
display: flex;
flex-direction: column;
gap: 1rem;
padding: 1.25rem;
}
.card__image {
width: 100%;
aspect-ratio: 16/9;
object-fit: cover;
border-radius: 8px;
}
/* Wider container: side-by-side layout */
@container (min-width: 480px) {
.card {
flex-direction: row;
align-items: flex-start;
}
.card__image {
width: 180px;
aspect-ratio: 1;
flex-shrink: 0;
}
}
/* Very wide container: larger typography */
@container (min-width: 700px) {
.card__title { font-size: 1.5rem; }
.card__desc { font-size: 1rem; }
}
Now this card looks correct in a 1-column feed, a 3-column grid, and a narrow sidebar - with zero changes to the component markup.
A card component can look correct in a 1-column feed, a 3-column grid, and a narrow sidebar with zero changes to the markup.
What Are the New Container Query Units?
CSS also introduces new units based on container size. There are six of them in the specification, and each maps directly to a dimension of the nearest containment context rather than the viewport, so an element sized in cqi scales with the box around it instead of the browser window. According to MDN's container size and style queries reference, cqi and cqb track the logical inline and block axes, which makes them the safer default in right-to-left or vertical writing modes, while cqw and cqh map to the simpler physical width and height that most developers reach for first.
| Unit | Equivalent to |
|---|---|
cqi | 1% of inline size |
cqb | 1% of block size |
cqw | 1% of container width |
cqh | 1% of container height |
cqmin | Smaller of cqw/cqh |
cqmax | Larger of cqw/cqh |
.card__title {
font-size: clamp(1rem, 4cqi, 2rem);
/* scales with container width, not viewport */
}
Scaling type with cqi is one part of the picture; the other is choosing the right typeface and scale ratios so the typography reads well at every size the container allows. The web typography and font pairing guide on Art of Styleframe covers type scale construction, variable font setup, and the clamp()-based fluid typography approach that pairs directly with container query units.
What Are CSS Style Queries?
Style queries (newer than size queries, and with partial support in Chromium and Safari) let you query CSS custom property values:
@container style(--layout: horizontal) {
.card {
flex-direction: row;
}
}
This enables "variant-driven" component styling from outside via CSS variables. The same custom property can steer a single value from inside the element, which is what CSS if() inline conditionals do, and if() can read the element's own property where a container query can only look at its ancestors.
Why Does a Container Collapse to Zero Width?
This is the trap nobody warns you about. container-type: inline-size applies inline-size containment, which tells the browser the element's width must not depend on its contents. A side effect is that the element reports no intrinsic width at all. Wherever the layout already hands the box a width, you never notice. Wherever the box is supposed to size itself from what's inside it, there's nothing to size from.
I measured the same container, a div holding a heading and a sentence, in nine layout contexts, with and without container-type: inline-size. Headless Chromium 151.0.7922.34, Apple M1, 2026-10-16, a 1000px-wide page, widths from getBoundingClientRect():
| Where the container sits | Without container-type | With inline-size |
|---|---|---|
| Block child | 1000px | 1000px |
Grid track, 1fr | 1000px | 1000px |
Flex item, flex: 1 | 1000px | 1000px |
| Table cell | 214px | 214px |
Grid track, auto | 590px | 484px |
| Flex item, auto width | 214px | 0px |
display: inline-block | 214px | 0px |
float: left | 214px | 0px |
position: absolute | 214px | 0px |
In the four collapsed rows the height jumped from 40px to 192px, because the text inside wrapped word by word into a zero-width box. Nothing threw, nothing logged. The card simply became a thin vertical sliver, and the usual first guess, that the @container rule is wrong, sends you to the wrong place.
The auto grid track is the quieter case. The container didn't vanish, it just came out 106px narrower, because the auto track no longer got a width contribution from it.
Putting container-type: inline-size on a flex item with auto width, an inline-block, a float or an absolutely positioned box collapses it to 0px wide, because inline-size containment removes the intrinsic width those layouts size from.
The fix is boring. Give the container a width the layout can use: flex: 1 or a flex-basis, a real grid track, width: 100%, or a wrapper that has one. Notice that flex: 1 and 1fr both worked above, which is the pattern. Anything that gets its width from the parent is safe, anything that asks the child how wide it wants to be isn't. So when a card inside a flex row suddenly disappears after you add container-type, check the flex item's width before you touch the query.
Does a Container Query Cost More Than a Media Query?
The common worry is that every container is a place the engine has to stop, measure and resume, so a page full of them must be slow. I wanted a number, and I wanted it for the situation people actually fear: a lot of cards, resized.
The test page is a grid of 300, 1,000 or 3,000 cards inside an iframe, so the iframe's width acts as the viewport for media queries and for layout. I switch it between 1200px and 780px. At 1200px the grid has four narrow columns and the cards stack; at 780px it has two wide columns and the cards go horizontal. Each sample is the time to apply the width and force style and layout, measured inside the page. Five variants run interleaved, one resize pair of each in turn, so a load spike lands on all of them instead of the one that happened to be running.
- none: no query at all, the cost of the resize itself
- media: a
@media (max-width: 1000px)rule switches the card layout - perCard: every card wrapped in its own
container-type: inline-size, with an@containerrule - perCardNoQuery: the same N containers and no
@containerrule - single: one container, the grid, with an
@containerrule
Before comparing speed I made the script check that media, perCard and single produce identical boxes for the first and last card at both widths. A speed comparison between two layouts that render differently would be worthless. They matched at every size.
Median milliseconds for one resize to 780px plus one back to 1200px, run 1, with the ratio to the media-query version in brackets:
| Cards | none | media | perCard | perCardNoQuery | single |
|---|---|---|---|---|---|
| 300 | 4.2 | 17.9 | 20.0 (1.12x) | 4.9 | 17.6 (0.98x) |
| 1,000 | 13.7 | 61.4 | 63.1 (1.03x) | 15.6 | 52.5 (0.86x) |
| 3,000 | 46.7 | 170.8 | 188.0 (1.10x) | 47.8 | 170.5 (1.00x) |
A second, independent run landed on 1.12x, 1.06x and 0.98x for one container per card, and 1.00x, 1.10x and 0.82x for a single container. The two runs disagree about which of the two container layouts is faster at 1,000 cards, which tells you what that last digit is worth: nothing.
Here's what I'd actually take from it. The cost of a media query, a container query per card and a single container all sit in the same band, between 0.82x and 1.12x of each other, and the sign flips between runs. I can't tell you container queries are faster, and I can't tell you they're slower. The expensive part of the resize is the layout switch itself, which is roughly three quarters of the time in every column, not the thing that decides to switch.
One direction did hold in both runs. Adding container-type to every card without writing a single @container rule cost between 2% and 17% more than no containment at all, in all six pairs. That's the "small layout cost" people mention, and it's small.
The caveats are not decoration. One engine, headless Chromium. One layout, a card grid, where the interesting work is in layout rather than style. The machine was shared with other jobs the whole time, with a load average above 25, so the absolute milliseconds are inflated and noisy. And I measured resize, not first paint or a long scroll, so I can't speak to those.
At 300, 1,000 and 3,000 cards, one container per card cost 0.98 to 1.12 times as much as an equivalent media query to resize in headless Chromium 151, and the sign flipped between two runs, so there's no measurable penalty either way.
What Is the Browser Support and Fallback Story?
Container queries (size type) landed in all major browsers between mid-2022 and early 2023. Chrome 105 (August 2022) shipped first, Safari 16 followed in September 2022, and Firefox 110 arrived in February 2023. As of early 2026, global support sits at roughly 93% according to caniuse.com. That's high enough that you don't need to guard every query behind a feature check for new projects.
That said, 7% is still real users. Here's how to handle them without breaking layouts.
Chrome 105 shipped size-type container queries first in August 2022, Safari 16 followed a month later, and Firefox 110 closed the gap in February 2023, which is why global support crossed 93 percent by early 2026 according to caniuse tracking.
Progressive enhancement with @supports:
/* Default layout - works everywhere */
.card {
display: flex;
flex-direction: column;
}
/* Only apply container query if supported */
@supports (container-type: inline-size) {
.card-wrapper {
container-type: inline-size;
}
@container (min-width: 480px) {
.card {
flex-direction: row;
}
}
}
The fallback stacks vertically - not ideal, but functional. Older browsers simply ignore the @supports block.
PostCSS plugin option: If you need broader compatibility, @csstools/postcss-container-queries compiles container queries into a JavaScript-driven polyfill at build time. I'd only reach for this on sites where IE 11 or older Android WebViews are genuine concerns - for most React or Astro apps, native browser support is sufficient.
Style queries: Chrome and Edge have supported @container style() for custom-property conditions since Chrome 111, Safari picked it up in 18.0, and Firefox followed in 151 (released May 19, 2026). All three engines now handle the custom-property form, so the old "Firefox is the holdout" caveat no longer applies. Two limits remain: Safari's support is partial (the document element can't be a container), and the range syntax inside style() is not in Safari yet. Keep style queries as progressive enhancement for anything that must work on older Firefox ESR builds, and put a @supports guard around them if you ship to those. For the cases where the condition lives on the same element, a plain custom property or a data- attribute selector is often simpler.
One practical tip: don't add container-type to every element by default. Apply it only to wrapper elements where you actually write @container queries. The measured cost of a bare containment context is small, as the next section shows, but the width collapse described there is a good reason on its own to keep the list short. And if you're still deciding between Grid and Flexbox inside those containers, check out the CSS Grid vs Flexbox comparison for a clear decision framework.
When Should You Use Container Queries vs Media Queries?
- Container queries: Component-level adaptation (cards, widgets, sidebars)
- Media queries: Page-level layout (number of columns, navigation pattern, font scale)
- Both: A responsive page layout (media query) containing adaptive components (container queries)
Here's how to check whether a component is a good candidate for container queries:
- Check if the component gets reused in more than one layout context, like a sidebar and a main grid. If it doesn't, media queries alone are simpler.
- Check if the component's markup ever needs a variant class or prop just to handle placement. That's the strongest sign container queries will remove code.
- Check current browser support against your analytics. At roughly 93% global support in 2026, most audiences can drop the
@supportsfallback entirely. - Check whether you need height-based queries. If so, add
contain: sizeand an explicit height, sinceinline-sizealone only tracks width.
Start adding container-type: inline-size to your component wrappers today. It's a low-risk addition and immediately unlocks better responsive behaviour across your component library. The pattern is straightforward: one property on the wrapper, one @container block per breakpoint you care about.
Where Can You Read More?
- MDN: CSS Container Queries - complete specification, browser support, and named container reference
- Can I use: CSS Container Queries - live browser support table
- MDN: Container query length units - full reference for
cqi,cqb,cqw,cqh,cqmin,cqmax
What Else Is Worth Reading?
- CSS Grid vs Flexbox: How to Choose the Right Layout - container queries work best when you've already picked the right layout tool for your component structure
- React Hooks pitfalls - if you're building React components with container-query-driven layouts, solid hook patterns keep your resize logic clean
- shadcn/ui - copy-paste component library built on Tailwind CSS; container queries make its Card and layout components truly context-aware
- Radix UI - unstyled accessible primitives you can style freely with container-query-driven CSS
- Headless UI - Tailwind-first components from the Tailwind Labs team that pair naturally with container query layouts