CSS container queries fixed the one thing media queries could never do: let a component respond to its own container's size instead of the whole viewport.
CSS container queries let an element style itself based on the size of its nearest ancestor with container-type set, rather than the browser window. A card component can now genuinely be "responsive" on its own terms — rendering differently in a 300px sidebar versus a 900px main column — without any JavaScript measuring ResizeObserver output and toggling classes.
Why Container Queries Matter (and When to Skip Them)
Before container queries, truly reusable responsive components were a myth — a card designed to look good at "desktop width" in a media query broke the moment you dropped it into a narrow sidebar, because @media only ever knows about the viewport, never the component's actual available space. Container queries fix this at the CSS layer.
Skip them for page-level, structural layout decisions (overall nav, header, page grid) — those genuinely are viewport-driven, and media queries are the right and simpler tool there.
Getting Started with Container Queries
Mark a container, then query against it:
.card-wrapper {
container-type: inline-size;
container-name: card;
}
@container card (min-width: 400px) {
.card {
display: flex;
gap: 16px;
}
.card img {
width: 160px;
}
}
@container card (max-width: 399px) {
.card {
display: block;
}
.card img {
width: 100%;
}
}
The same .card component now automatically switches between a horizontal layout (in a wide container) and a stacked layout (in a narrow one), based purely on the space it's actually given — no JavaScript, no duplicate component variants.
Core Container Query Concepts Every Developer Should Know
container-type: inline-size is the setting you'll use almost always — it queries the container's width (the "inline" dimension in horizontal writing modes). container-type: size queries both width and height, but requires the container to have an explicit size, which is rarer in practice.
container-name scopes queries to a specific container when you have nested containers, so a @container rule doesn't accidentally match the wrong ancestor:
.sidebar { container-type: inline-size; container-name: sidebar; }
.card { container-type: inline-size; container-name: card; }
Container query units (cqw, cqh, cqi) size relative to the container, not the viewport — the container equivalent of vw/vh:
.card-title {
font-size: clamp(1rem, 5cqi, 1.5rem);
}
A container can't query itself. container-type must be set on an ancestor, and the @container rule styles descendants — you can't set both on the same element expecting it to respond to its own size.
Common Container Query Mistakes and How to Fix Them
Mistake 1: forgetting to set container-type on the parent. Without it, @container rules simply never match — a silent failure that's easy to miss. Fix: always pair a @container block with a corresponding container-type declaration on the intended ancestor.
Mistake 2: using container queries for page-level layout. This adds indirection for no benefit when the page itself is effectively the container — a media query is simpler and clearer for structural, page-wide decisions.
Mistake 3: not naming containers in nested contexts. Unnamed @container rules match the nearest container-typed ancestor, which can be the wrong one in deeply nested layouts. Fix: name containers explicitly whenever nesting is more than one level deep.
When Should You Use Container Queries Instead of Media Queries?
Use container queries for reusable components meant to work in multiple layout contexts — cards, widgets, sidebars, anything a design system ships as a standalone unit. Use media queries for overall page structure and navigation, where viewport size genuinely is the right signal.
Container Queries in Production
Browser support is now solid across all major evergreen browsers, so there's little reason to hold off adopting them for component libraries. For design systems specifically, container queries are the missing piece that finally makes "build once, use anywhere" responsive components actually true — worth prioritizing over continuing to hand-write per-page responsive overrides for shared components.
Next time you duplicate a component to handle "the sidebar version" and "the full-width version," check if a container query collapses both back into one component.