Container Queries

Why media queries are not enough

You already know media queries: they react to the viewport (the whole screen) — for example “below 600px, stack the cards”. But the same component often lives in different places: a product card might be full-width on one page and squeezed into a narrow sidebar on another. The screen size is identical in both, yet the card needs to look different.

Container queries solve this. Instead of asking “how wide is the screen?”, they ask “how wide is my container (my parent box)?” — so a component can adapt to the space it is actually given, no matter where you drop it.

The two steps

Setting up a container query is always the same two steps:

1. On the parent box, declare it a container with container-type: inline-size (this means “measure my width”). Optionally give it a name with container-name.
2. Write a @container rule — just like @media, but it tests the container’s width instead of the screen’s — and put the styles that should change inside it.

A card that adapts to its container

Below, the same card markup is placed in a wide box and a narrow box. With container queries, the wide one lays its image and text side by side, while the narrow one stacks them — even though the screen size never changed. Read the code, then the breakdown:

<style>
  /* Step 1: mark the wrapper as a query container */
  .col { container-type: inline-size; border: 1px dashed #c7d2fe; padding: 8px; border-radius: 10px; }
  .wide { width: 100%; margin-bottom: 14px; }
  .narrow { width: 230px; }

  .card { background: #eef2ff; border-radius: 10px; padding: 12px; }
  .card img { width: 100%; border-radius: 8px; }
  .card h4 { margin: 8px 0 4px; color: #4338ca; }

  /* Step 2: when the CONTAINER is at least 380px wide, go side-by-side */
  @container (min-width: 380px) {
    .card { display: flex; gap: 12px; align-items: center; }
    .card img { width: 120px; }
  }
</style>

<div class="col wide">
  <div class="card">
    <img src="https://picsum.photos/200/120" alt="photo">
    <div><h4>Wide container</h4><p>Image and text sit side by side.</p></div>
  </div>
</div>

<div class="col narrow">
  <div class="card">
    <img src="https://picsum.photos/200/120" alt="photo">
    <div><h4>Narrow container</h4><p>Same card — now stacked.</p></div>
  </div>
</div>

The two cards have identical markup, yet they look different because each sits in a container of a different width. Here is why:

• container-type: inline-size on .col — this is the key line. It tells the browser “measure this box’s width and let children query it”. (“Inline size” means width in a normal left-to-right page.)
• @container (min-width: 380px) { ... } — reads just like a media query, but it checks the nearest container’s width, not the screen. The wide .col is over 380px, so its card switches to display: flex (image beside text). The narrow .col is only 230px, so the rule does not apply and its card stays stacked.
• Resize the whole preview and notice: even on a wide screen, the narrow card stays stacked — because it is the container, not the screen, that decides.