Why container queries outclass media queries

Container queries resemble media queries closely enough that the instinct is to swap one for the other and change nothing else. Doing that leaves their main advantage on the table: a media query knows very little, and a container query knows about the thing you are actually trying to size.

A media query has access to exactly two pieces of information: the viewport dimensions and the browser's font size. That second item trips people up constantly.

The font size a media query reads is not your root font size

Consider a query that switches a background color once the viewport hits a width expressed in em units. Many readers multiply out the value against their document's root font-size and expect the breakpoint to land accordingly — a common guess, and a wrong one.

html {
  font-size: 32px;
}

body {
  background: lightsalmon;
}

@media (min-width: 35rem) {
  body {
    background: lightseagreen;
  }
}

The font size media queries consult is the initial size supplied by the browser before any declarations run, including user agent styles. That defaults to 16px and can be altered in browser settings. This behavior is intentional; the media query specification states that relative length units in media queries are based on the initial value, so units are never based on the results of declarations.

Were it otherwise, a rule that resized the root element from inside a media query tied to that same font size would oscillate: at a 480px viewport the font size would grow, then shrink, then grow again, forever.

html {
  font-size: 16px;
}

@media (min-width: 30rem) {
  html {
    font-size: 32px;
  }
}

Designing against the container instead of the viewport

Container queries are not exposed to that feedback loop, which frees them for layout work that media queries can only approximate. Suppose a grid should stack when narrow and show three columns when wide. With media queries you hunt for the exact viewport width where that happens — essentially picking a magic number. With a container query you state the minimum acceptable column size and let the container's own width decide. Three columns at a 300px minimum means three columns once the container reaches 900px; a media query at 900px fails because the container is usually narrower than the viewport at that point.

Container queries also accept any unit, because they can read the font size of the container itself. ch suits this well: "give me three columns once each can hold at least 30 characters."

.grid-parent { container-type: inline-size; }

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

  @container (width > 90ch) {
    grid-template-columns: repeat(3, 1fr);
  }
}

That arithmetic can also be handed to the browser, since calc() is valid inside media and container queries alike: @container (width > calc(30ch * 3)).

The wrapper problem, and a way around it

Container queries carry one structural annoyance: a container cannot query itself, so an ancestor wrapper is required above whatever the query targets. It gets worse when grid or flex children should respond to their own available space — a parent acting as the container does not give you that, so each item needs its own wrapper.

<div class="grid">
  <div class="card-container">
    <div class="card">
  </div>
  <div class="card-container">
    <div class="card">
  </div>
  <div class="card-container">
    <div class="card">
  </div>
</div>
.card-container { container-type: inline-size; }

It works, but it is tedious. Helpfully, when the grid uses repeat(auto-fit, ...), the main grid itself can serve as the container.

.grid-auto-fit {
  display: grid;
  gap: 1rem;
  grid-template-columns: repeat(auto-fit, minmax(min(30ch, 100%)), 1fr);
  container-type: inline-size;
}

Since each column's minimum is known to be 30ch, that fact can drive per-item styling based on how many columns currently fit.

/* 2 columns + gap */
@container (width > calc(30ch * 2 + 1rem)) { ... }

/* 3 columns + gaps */
@container (width > calc(30ch * 3 + 2rem)) { ... }

In the example, the first grid child restyles according to whether one, two, or three columns are present. Background colors merely demonstrate the mechanism; the same technique supports far more substantial changes.

One real limitation

The approach's only notable gap is that breakpoints cannot be declared as custom properties, which would improve the developer experience considerably. Custom media queries appear in the editor's draft of Media Queries Level 5, but they have sat there for some time without browser movement, so availability may be distant. Even without them, the readability and maintainability gains do not outweigh the usefulness of the technique.

Flexbox: workable, with a padding trap

Flexbox behaves differently because the items themselves define the layout, so the sizes set on items are what matter to the breakpoint. It functions, but a significant pitfall exists.

.flex-container {
  display: flex;
  gap: 1rem;
  flex-wrap: wrap;

  container-type: inline-size;
}

.flex-container > * {
  /* full-width at small sizes */
  flex-basis: 100%;
  flex-grow: 1;

  /* when there is room for 3 columns including gap */
  @container (width > calc(200px * 3 + 2rem)) {
    flex-basis: calc(200px);
  }
}

The example uses px, though any unit would do here just as with grid. Media queries could theoretically handle this too, calc() included, but only when the parent's width matches the viewport width — rarely true in practice.

The trap is padding. The flexbox algorithm ignores padding and borders even when box-sizing is changed, so padded flex items force you back into magic-number territory. Adding padding alone, with nothing else touched, eventually produces an awkward two-column arrangement with one item stretched across the bottom.

That is why the grid version tends to get more use than the flexbox one, though there are cases where flexbox still fits. Knowing the current column count lets you build layouts that adapt to the space an element actually has — a capability media queries never offered.