Container queries: sizing components by their container instead of the viewport

What it is

A media query asks how wide the viewport is; a container query asks how wide a particular ancestor is. An element becomes a query container with container-type: inline-size (queries on the inline axis) or size (both axes), optionally named with container-name. Rules inside @container (width > 40em) { .card { … } } apply to descendants according to the nearest ancestor with a containment context, or the named one when a name is given. MDN lists container-relative units (cqw, cqh, cqi, cqb, cqmin, cqmax), each 1% of the container's dimension, usable wherever a length is allowed, for example in font-size.

Why it matters

A component placed in a sidebar, a main column and a modal cannot infer its available room from the viewport width. With viewport breakpoints, every placement needs its own overrides; with container queries, the component carries its breakpoints and adapts wherever it is dropped. This is what makes design-system components reusable across layouts rather than across pages.

How to apply

• Make the wrapper the container, not the component itself. An element cannot respond to its own size: the content would change the size and flip the query, which MDN describes as an endless loop and the reason size containment is applied.
• Prefer inline-size. The size value also contains the block axis, so the element stops growing with its content unless it has an explicit height.
• Name containers when components nest (container-name: card) and query by name, so an inner query does not match an unintended ancestor.
• Use cqi for fluid type and spacing inside a component, wrapped in clamp() so extremes stay readable.
• Keep viewport media queries for page-level layout (column count, navigation) and container queries for components; the two coexist.
• Breakpoints inside @container must be literal values, since custom properties are not allowed in query conditions; keep them in one place per component.

Pitfalls

Containment changes layout: an inline-size container's width must come from context (a block-level element stretching to its parent) or be set explicitly, otherwise it collapses and the query never matches. Container style queries (@container style(--x: y)) are a separate feature; check their support separately from size queries. A query container that is itself sized by its children (a flex item with flex: 0 0 auto, an absolutely positioned box with no width) is the usual cause of "the query never fires".