Container Query

Definition

A container query decides how to lay something out based on the size of the parent element that holds it, not the size of the whole screen. The same card component can place its image and text side by side when it sits in a wide spot, then stack them top to bottom when it lands in a narrow one, reshaping itself on its own. Where a breakpoint looks at the size of the entire window to make its call, a container query looks at the width of the actual slot the element is standing in. You reach for it through the modern CSS @container rule when you want a component to adapt to the context it happens to be placed in.

Why does it matter?

Modern screens reuse a single component in many different spots. The same product card shows up in a wide article body, in a narrow sidebar, and inside a two-column grid. If your only yardstick is the screen width, a card dropped into a cramped sidebar will still insist on a horizontal layout just because the screen is wide, squishing itself into something awkward. A container query lets each card read the width of its own slot directly, so it appears in a shape that fits wherever it lands. Because of that, one well-built component can be reused in many places without being tweaked for each spot, which lifts the consistency and maintainability of your design system. Since the component takes responsibility for its own context, you can later change the layout or move it to a new spot without ever having to touch the card again.

Common mistakes

• Forgetting to declare the parent as a container. An @container rule only works if the parent you want to target has a container-type set on it, and if you skip that declaration the rule is silently ignored and nothing changes at all.
• Pushing container queries into every situation. Reshaping the big skeleton of the whole page is still a better fit for breakpoints. Container queries shine brightest on self-contained components that get reused from spot to spot.
• Letting a child change the size of the very parent you designated as the container. If the container grows again in response to its child, that loop can make the layout jitter, so keep a clear split between the parent that sets the size and the child that reacts to it.

Practical tips

• Reach for a container query whenever the right yardstick is the slot an element sits in rather than the whole screen. Since the card adapts to its own width in a sidebar or an article body alike, this fits especially well when you are building components meant to be reused anywhere.
• Prepare a fallback with @supports for environments where support is not yet complete. If you make sure the component still shows a reasonable default, like a simple vertical stack, even without container queries, your content stays intact and safe in any browser.
• Naming your containers lets you pick exactly which parent to measure against even when several are nested. Even in a complex structure where a card sits inside another card, the layout reacts to the container you intended and avoids surprise shifts.

Related concepts