CSS container queries: components that fit their space

A product card sits in the main column and looks right: image on the left, text on the right. Then someone places the same card in a narrow sidebar. The screen is still wide, so the media query still applies the wide layout, and the card is crushed.

The card should not care how wide the screen is. It should care how much room it has. That is what container queries provide.

The two steps

First, mark an element as a container. Second, write rules that depend on that container's width.

.card-wrap {
  container-type: inline-size;
  container-name: card;
}

.card {
  display: grid;
  gap: 1rem;
}

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

<div class="card-wrap">
  <article class="card">
    <img src="/img/mug.webp" alt="Blue ceramic mug" width="400" height="400" />
    <div>
      <h3>Ceramic mug</h3>
      <p>৳ 450</p>
    </div>
  </article>
</div>

When the wrapper is at least 28rem wide, the card lays out side by side. When it is narrower, the card stacks. Put it in the main column, a sidebar or a three column grid, and it picks the right layout each time.

Details that save time

• A container cannot query itself. The element with container-type is the one being measured. The rules apply to its descendants. That is why the example has a wrapper.
• inline-size is the usual choice. It watches the width only. The value size also watches the height and requires the container to have a defined height.
• Naming is optional but wise. Without a name, a rule matches the nearest container. With nested containers, names remove the guesswork.
• There is a shorthand: container: card / inline-size;.

Container units

Inside a container, cqi is one percent of its inline size. It makes type and spacing scale with the component.

.card h3 {
  font-size: clamp(1.125rem, 4cqi, 1.75rem);
}

Media queries still have a job

A typical page uses both. Media queries arrange the page, and container queries let each component adapt to the slot it was given.

Browser support

Size container queries work in all current major browsers and have done so since 2023. For older ones, write the narrow layout as the base style. A browser that ignores @container then shows the stacked version, which works everywhere.

Why it matters

Container queries make components portable in practice. A design system can ship a card, a table or a form that behaves correctly wherever it is dropped, without a list of special cases per page. That means less CSS to maintain and fewer layout bugs when a page is rearranged.

It is also a good example of the web platform closing a long-standing gap. See what the Interop project fixes for how features like this now reach every browser.