ZipKit
Glossary

Container queries

Container queries are a CSS feature that apply styles to an element based on the size of its nearest ancestor query container instead of the browser viewport. They are defined in the W3C CSS Containment Module Level 3 through the container-type property, the @container rule and the cqw and cqi units. The thing people search for most is that the container must opt in with container-type.

How it works

You mark an ancestor as a query container with container-type, then write an @container rule that tests that ancestor's size. Descendants matching the rule get the styles, and the browser re-evaluates the rule whenever the container resizes.

  • container-type: inline-size makes the element a container for queries on its inline axis (width in horizontal writing modes). It applies layout, style and inline-size containment.
  • container-type: size allows queries on both axes. It applies size containment, so the box no longer takes its height from its content and needs an explicit height.
  • container-type: normal is the initial value. The element is not a size container.
  • container-name gives the container a name that an @container name (...) query can target. Without a name, the query matches the nearest ancestor that is a query container for that axis.

The element that carries container-type can never be styled by its own query. Only its descendants are affected, which is what prevents circular sizing.

.card { container-type: inline-size; container-name: card; }
.title { font-size: 16px; }
@container card (inline-size > 400px) { .title { font-size: 28px; } }
.note { font-size: 10cqi; }

Run in headless Chromium 141 with two .card wrappers, one 300px wide and one 500px wide:

300px card title: 16px
500px card title: 28px
300px card .note (10cqi): 30px
500px card .note (10cqi): 50px

What are cqw and cqi units?

cqw is 1% of a query container's width, and cqi is 1% of its inline size. The full set is cqw, cqh, cqi, cqb, cqmin and cqmax, where cqmin and cqmax pick the smaller or larger of cqi and cqb. If no ancestor qualifies as a container on that axis, the unit falls back to the small viewport size. In the run above, 10cqi with no container on a 1000px viewport computed to 100px.

Container queries vs media queries

A media query asks about the viewport or device, so the same card looks identical in a wide main column and a narrow sidebar. A container query asks about the card's own box, so one component can be dropped anywhere and respond to its slot.

Common pitfalls

  • Forgetting container-type: an @container rule with no ancestor that has container-type: inline-size or size never matches. Add the property to the wrapper, not to the element you want to change.
  • Using size and losing height: container-type: size applies size containment, so an auto-height container collapses to zero height. Use inline-size unless you really query height.
  • Styling the container itself: a query cannot restyle the element that has container-type. Put the changing styles on a child.
  • Expecting cq units to need no container: without an eligible ancestor, cqi quietly uses the small viewport, so a missing container looks like a wrong size, not an error.
  • Querying a name that does not exist: @container sidebar (...) matches nothing if no ancestor has container-name: sidebar.

Related terms

  • CSS Grid — grid tracks often supply the container width that a query reads.
  • Flexbox — flex items inside a container can switch layout through a query.
  • Viewport units — the viewport-based counterpart to cq units.
  • Feature queries — the other conditional rule in CSS, testing support instead of size.
  • CSS cascade — rules inside @container take part in the normal cascade.

See also