CSS container queries explained

CSS container queries let a component change its layout based on the size of the container it lives in, rather than the size of the whole viewport. They are the modern answer to a long-standing responsive-design problem: a card that works in a wide sidebar and a narrow mobile column cannot be written once with a single media query, because its available width depends on where it is placed. Container queries fix that by making the element's own container the reference.

Setting up a container

Before a query can run, an element has to declare itself a container with the container-type property. This is the step most people miss, and without it the query silently has nothing to respond to.

• container-type: inline-size makes the element queryable by its inline width, which is the block axis for horizontal text. This is the value you want for almost every layout component.
• container-type: size also establishes the block and inline containment of both dimensions, but it applies layout and style containment to the element, which usually makes it too aggressive for general use.
• container-type: normal turns off size querying for that element but still allows style queries.

Because every descendant can only be queried against its nearest ancestor container, you deliberately register the wrapper that sets the component's available width, not every element in the page. Registering too many containers adds containment cost, so choose the smallest set that models your reusable pieces.

You can also give a container a name with container-name, which lets you select a specific ancestor instead of relying on the nearest one.

Writing the query

With a container registered, use the @container at-rule to apply styles when the container meets a condition.

.card {
  container: card / inline-size;
}

@container card (min-width: 700px) {
  .card__grid {
    grid-template-columns: repeat(2, 1fr);
  }
  .card__title {
    font-size: 1.25rem;
  }
}

This reads as: when the .card container is 700 pixels wide or more, switch its grid to two columns and enlarge the title. The same .card component now lays out correctly whether it appears in a full-width page region or a half-width sidebar, with no JavaScript and no class toggling.

Container queries reached baseline widely available support across all major engines, which means they have been stable in production for several years. The main adjustment if you are coming from media queries is that the query condition is about the container, so a component's breakpoints no longer need to match the viewport breakpoints anywhere up the page.

Using container units

Alongside size queries you get container relative length units that resolve against the container dimensions. cqw is 1% of the container width, cqh 1% of its height, and cqi and cqb 1% of the inline and block axis respectively.

.card__title {
  font-size: 5cqi;
}

Because the unit resolves to the container rather than the viewport, a component scales its type in proportion to the space it actually has. This removes a whole class of fragile media-query overrides where the same element needed different font sizes in different page layouts.

Container queries work well alongside the other modern layout tools. Combine them with a reusable grid pattern for placement and @layer for a clean cascade, and reach for container queries whenever a component's look depends on its placement rather than on the viewport as a whole. See responsive CSS breakpoints for how they compare to viewport media queries.