Container Queries: Components That Adapt to Their Box

A card in a sidebar and the same card in a hero deserve different layouts — but they’re the same component. Media queries can’t tell them apart, because the screen width is identical. Container queries can.

Declare a containment context

Mark the parent as a query container, then style the child against the parent’s inline size:

.card-host { container-type: inline-size; }

.card { display: grid; gap: 0.75rem; }
@container (min-width: 28rem) {
  .card { grid-template-columns: 8rem 1fr; align-items: center; }
}

Now the card goes two-column whenever its box is at least 28rem wide — horizontal in a wide hero, stacked in a narrow rail, with no knowledge of the viewport.

Container query units

cqi, cqb and friends size against the container instead of the viewport. Padding of 4cqi breathes proportionally to the component, not the screen — exactly what you want for a card that appears at wildly different sizes.

Where they shine

Design-system components, bento tiles, anything you drop into slots of varying width. The rule of thumb: reach for a container query whenever the thing you’re styling can appear in more than one column width.

Progressive by default

Unsupported browsers simply ignore the @container block and get the stacked base layout — which you designed first anyway. Ship it without a polyfill.