Future CSS: Container queries

Originally published on alexpate.com.

One of the trickiest parts of web design is getting components to adapt not just to the viewport but to the space they’re actually given. A card that looks right in a wide column falls apart in a narrow one, and the viewport hasn’t changed at all.

Container queries fix this.

The limits of media queries

Media queries have been the backbone of responsive design for years, but they only ever look at the viewport, never at the container an element actually sits in.

So if you have a reusable card component that looks great in one section of your site but doesn’t quite fit in another, media queries can’t help you. Adjusting the card for each context by hand becomes a nightmare.

How container queries work

A container query styles an element based on the size of its parent container, so the same component can adapt wherever it’s placed.

You start by designating an element as a container, with the container-type property:

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

inline-size measures the container’s inline axis (usually width, in left-to-right languages); size measures both width and height. Once a container is declared, you can write styles that respond to it with the @container rule.

A practical example

Let’s build a card that adapts to its container’s width.

Try resizing the card below using the resize handle. When the card is wider than 500px, the text and image sit side by side. When it’s narrower, the text wraps below the image.

HTML structure

<div class="card-container">
  <div class="card">
    <img src="image.jpg" />
    <div class="content">
      <h2>Card Title</h2>
      <p>This is some sample text to illustrate the card component.</p>
    </div>
  </div>
</div>

CSS styling

/* Designate the container */
.card-container {
  container-type: inline-size;
}

/* Default card styles */
.card {
  display: flex;
  flex-direction: column;
}

/* Adjust card layout based on container width */
@container (min-width: 500px) {
  .card {
    flex-direction: row;
    align-items: center;
  }
}

I’ve trimmed the presentational styles here so the container query itself stands out.

The .card stacks its content vertically by default. When its parent .card-container is at least 500 pixels wide, it switches to a horizontal layout.

When to use container queries

Anywhere a component can’t know how much room it will get: cards that appear in both a main column and a sidebar, anything nested inside grids or flex layouts, and design system components that have to survive whatever page they land on.

Media queries vs container queries

With a media query:

@media (min-width: 800px) {
  .sidebar {
    width: 250px;
  }
}

This adjusts the .sidebar based on the viewport width, which might not be what you want if the sidebar is inside a narrower container.

With a container query:

.sidebar-container {
  container-type: inline-size;
}

@container (min-width: 500px) {
  .sidebar {
    width: 250px;
  }
}

Here the sidebar responds to .sidebar-container, so it behaves the same wherever that container ends up.

Gotchas

Before you sprinkle container queries all over your stylesheet, two things worth knowing.

Browser support

Container queries are safely in “just use it” territory these days. As of September 2026 they’ve been supported in every major browser for years: Chrome and Edge since 105, Safari since 16, and Firefox since 110, all shipped across 2022 and 2023. Unless you’re supporting truly ancient browsers, there’s nothing to check before deploying to production.

Performance

Container queries aren’t free. Applied to very deep or complex DOM trees they add layout overhead, so if you’re leaning on them heavily, test the impact.

Further reading

Container queries remove a whole category of viewport hacks: components can finally be styled against the space they occupy rather than the screen they happen to be on.

• MDN: CSS Container Queries
• Can I Use: CSS Container Queries