Every frontend developer has written a media query that made perfect sense in isolation and then broke the moment a designer decided a component should also live in a sidebar. We had a product card component used in three places on a client's e-commerce site: a full-width grid, a two-column recommendation strip, and a narrow cart sidebar. Three placements, one component, and it looked correct in exactly one of them at any given viewport width. The fix wasn't more media queries. It was container queries.

The core problem with viewport-based breakpoints

Media queries answer the question "how wide is the browser window," which is almost never the question you actually care about. What you care about is "how much horizontal space does this specific component have right now," and those two numbers diverge constantly. A 1440px-wide browser window tells you nothing useful about a card that's sitting in a 280px sidebar. We ended up with a `.card--compact` class, a `.card--sidebar` class, and a growing pile of `!important` overrides that a junior dev on the team eventually described, accurately, as "CSS Jenga."

What changed

Container queries flip the question. Instead of asking the viewport, the component asks its own parent container. You mark an element as a containment context with container-type, and every descendant can query against that container's size instead of the window's.

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

.card {
  display: grid;
  grid-template-columns: 1fr;
  gap: 0.5rem;
}

@container card-grid (min-width: 380px) {
  .card {
    grid-template-columns: 120px 1fr;
    gap: 1rem;
  }
}

@container card-grid (min-width: 600px) {
  .card {
    grid-template-columns: 160px 1fr;
  }
  .card__description {
    -webkit-line-clamp: 4;
  }
}

Drop that same card into a 250px sidebar and a 900px main grid, and it just works. No modifier classes, no JavaScript ResizeObserver hacks, no duplicate components. We deleted eleven CSS classes and about 40 lines of override logic from that one component. The card doesn't know or care where it lives; it only reacts to the space it's actually given.

Where we still got surprised

Container queries aren't a drop-in replacement for every media query, and treating them as one will bite you. Page-level layout decisions — should the whole site switch to a mobile nav, should the sidebar collapse — those are genuinely viewport concerns, and media queries are still the right tool. We tried converting our top-level layout breakpoints to container queries early on and it added a layer of indirection with zero benefit. Save container queries for components that are reused in genuinely different contexts, not for your outermost page shell.

The other gotcha: a containment context creates a new formatting context, which quietly changes how some CSS properties behave, including certain uses of `position: sticky` inside the container. We had a sticky "add to cart" button inside a card that queried its container and it stopped sticking correctly on Safari until we moved the sticky element outside the containment boundary. Test on real Safari, not just Chrome dev tools, before you ship this to production.

Browser support, honestly

As of writing, container query support is solid across Chrome, Edge, Firefox, and Safari on anything reasonably current, which covers the overwhelming majority of traffic on most commercial sites. If you're supporting genuinely old enterprise browsers you'll want a fallback, but for most consumer-facing products the "can I use this in production" question has already been answered yes for a while now. We shipped this on a live storefront with real traffic and got zero layout-related support tickets in the following month, which for a CSS change touching every product card on the site, is about as good a result as you can hope for.

The actual takeaway

Container queries don't make responsive design easier in the abstract sense people market them as. What they do is let a component's responsiveness live where the component's styles already live, instead of scattered across a global stylesheet full of viewport assumptions that stop being true the moment a designer reuses your component somewhere new. If you've got components that get reused in wildly different layout contexts, this is the tool. If your layout is mostly a single-column page with a couple of breakpoints, you probably don't need it yet, and that's fine too.