Container Queries

Media queries let you style elements based on the size of the browser viewport, but that has always been an awkward fit for reusable components: a card component might sit in a wide main column on one page and a narrow sidebar on another, and its ideal layout depends on the space it actually has — not on the overall screen size. Container queries solve exactly this problem by letting an element respond to the size of its containing element instead of the viewport.

Container queries are a genuinely modern CSS feature (broadly supported in evergreen browsers since 2023) and represent one of the most requested capabilities in CSS's history, because component-based design (React, Vue, design systems) had outgrown what viewport-based media queries could express.

Why it matters

A media query asks how wide the window is, but a reusable component needs to know how wide its own container is: the same card may sit in a narrow sidebar or a wide main column on the same screen. Container queries answer that, and they are the most significant addition to responsive design in years. All current browsers support them.

Declaring a Containment Context

To make an element queryable by its children, you opt it in with container-type on the parent: container-type: inline-size (the common case, tracking width) or size (tracking both width and height). An optional container-name lets you target a specific container by name when queries could otherwise be ambiguous.

Writing an @container Rule

Inside a rule, @container (min-width: 400px) { ... } applies its nested styles whenever the nearest ancestor with a containment context is at least 400px wide — regardless of how wide the browser window itself is. This is the key difference from @media, which only ever looks at the viewport.

Why This Beats Media Queries for Components

A card component styled with container queries looks correct whether it's dropped into a full-width page, a narrow sidebar, or a three-column grid, because its internal layout reacts to its own available space rather than a global breakpoint. This makes components genuinely reusable across contexts — which is exactly the promise component libraries and design systems are built on — without the component needing to know or guess where it will be placed.

Example

<div class="card-container">
  <div class="card">
    <img src="avatar.jpg" alt="">
    <div class="card-body">
      <h3>Asha Patel</h3>
      <p>Frontend Engineer</p>
    </div>
  </div>
</div>

<style>
.card-container {
  container-type: inline-size;
  container-name: card;
}

.card {
  display: flex;
  flex-direction: column;
}

@container card (min-width: 350px) {
  .card {
    flex-direction: row;
    align-items: center;
    gap: 16px;
  }
}
</style>

When .card-container is narrower than 350px (e.g. in a sidebar), the avatar image stacks above the text. When the same markup is placed in a wider container of 350px or more (e.g. a main content column), the layout automatically switches to a side-by-side row with the avatar next to the text — with no JavaScript and no change to the viewport width.

Exercise

Make main a query container. By default the heading is 1.25rem. When main itself is at least 400px wide, the heading grows to 2rem and the button gets larger padding of 1rem by 2rem.

Expected result: the heading and the button grow when main reaches 400px wide, whatever the width of the window.

/* The page contains: <main> with an <h1>, a <p> and a <button> */

main {
  /* TODO: make main a container that can be queried on its inline size */
}

h1 {
  font-size: 1.25rem;
}

/* TODO: when main is at least 400px wide, enlarge the heading
         and give the button more padding */

/* The page contains: <main> with an <h1>, a <p> and a <button> */

main {
  container-type: inline-size;
}

h1 {
  font-size: 1.25rem;
}

@container (min-width: 400px) {
  h1 {
    font-size: 2rem;
  }

  button {
    padding: 1rem 2rem;
  }
}

Quick quiz

Interview questions