CSS · layout · web standards

CSS container queries

A media query asks how wide the window is. A container query asks how much room this component actually has. Almost everything else about the feature follows from that one difference.

It matters because a component rarely occupies the whole viewport. A card in a sidebar and the same card in a three-column grid see identical media queries and completely different amounts of space - which is why the usual workaround was a modifier class like card--compact, applied by whoever placed the component and forgotten by whoever moved it.

The two lines that make it work

You declare an element as a container, then query it. Nothing else is required.

.card-list {
  container-type: inline-size;
  container-name: cards;
}

@container cards (min-width: 30rem) {
  .card { display: grid; grid-template-columns: 8rem 1fr; }
}

container-type: inline-size tells the browser to track the element's inline dimension - its width in horizontal writing modes - and to allow queries against it. The name is optional; without one, a component queries its nearest ancestor container.

The query itself reads like a media query and behaves like one, except that the thing being measured is an element rather than the viewport.

The rule people trip over

An element cannot query itself. If you set container-type on .card and then write @container rules targeting .card, nothing happens - and nothing warns you.

The container must be an ancestor of what you are styling. In practice that means declaring the container on the wrapper and styling the children inside the query. Once you have internalised that, most of the surprises disappear.

The second surprise is layout containment. container-type: inline-size makes the element's size independent of its contents in the inline direction, which is exactly what allows the browser to measure it without circular reasoning - but it also means an element that used to be sized by its children may now collapse. Check your wrappers after adding it.

Container query units

Alongside the queries come units relative to the container rather than the viewport: cqw and cqh for one percent of its inline and block size, plus cqi, cqb, cqmin and cqmax.

They are what makes truly portable typography possible - font-size: 4cqi scales a heading with the space the component was given, not with the browser window. Use them sparingly: text that scales continuously is easy to make unreadable at the extremes, and a couple of steps in a query is often kinder than a fluid formula.

Where this actually changes how you work

The honest answer is: in design systems, and much less elsewhere.

If you ship components that other people place in layouts you do not control, container queries remove an entire category of coordination. The component becomes responsible for its own adaptation, and the person using it no longer has to know which variant to pick.

If you build page-level layouts for a single site, media queries remain perfectly appropriate. The page really does respond to the viewport, and reaching for containers everywhere adds indirection without buying anything.

Support, and what to do about it

Container queries are supported across current versions of Chrome, Edge, Firefox and Safari, and have been for long enough that they are a normal tool rather than an experiment. The remaining question is your own support floor, not the feature's readiness.

If you must support older browsers, the graceful path is to write the component so that its default state - outside any @container rule - is the narrow one. Browsers that do not understand the query simply keep the compact layout, which is usable everywhere. Progressive enhancement works here precisely because the fallback is a real design rather than a broken one.

The short version

Set container-type: inline-size on the wrapper, query it with @container, and style the children - never the container itself. Reach for it when a component must work in places you do not control; keep media queries for the page. And design the un-queried state to be the narrow one, so that anything which does not understand the rule still gets something sensible.