Skip to content

CSS Container Queries: Build Responsive Components

CSS container queries let components adapt to their parent's width. Syntax, named containers, units, and real patterns - 93% browser support in 2026.

· · 15 min read

Updated: October 23, 2026

CSS @container rule with min-width query in a code editor

Quick Take

Container queries let a component adapt to its parent container width, not the viewport, so a card looks correct in a sidebar or a full-page grid without changing a line of CSS. They're at 93% browser support in 2026 and ready for production without polyfills.

Run this yourself. The measurement behind the two sections on cost and collapse: css-container-query-cost/ in the Coding Dunia code-examples repo. Headless Chromium, self-asserting, prints your machine's numbers.

CSS container queries are a layout feature that lets an element's styles respond to the size of its nearest containing element instead of the browser viewport, so a single component can adapt correctly no matter where it's placed on the page. Media queries check the viewport. CSS container queries check the container instead. This distinction is fundamental to building truly responsive, reusable components. Container queries (size type) are supported in all major browsers since Chrome 105, Safari 16, and Firefox 110 - overall support sits at around 93% as of early 2026.

Containment context is the term for the boundary a container query measures against - it's established by setting container-type on a parent element, and every @container rule inside that subtree resolves against that element's size rather than the viewport. Container query units, like cqi and cqw, are length units that resolve to a percentage of the nearest containment context's size instead of a percentage of the viewport.

What's Wrong with Media Queries for Component Design?

Imagine a Card component that looks great in a 3-column grid but breaks when placed in a sidebar. With media queries, you'd need to know the context at the component level - which defeats the purpose of encapsulation. According to MDN's containment documentation, a media query only ever has one piece of information available to it: the size of the viewport. It has no way to know whether the element it's styling sits in a 300px sidebar or a 1200px main column, so any component meant to be reused across contexts needs manual override classes for every placement.

Container queries solve this: the component adapts to wherever it's placed. The same Card markup, with zero JavaScript and zero variant classes, renders three or four visually distinct layouts depending purely on the pixel width of its parent.

A media query only ever knows the size of the browser viewport, never where an element actually sits on the page, which is why reusable components built around media queries always need manual override classes for every placement context. Container queries remove that dependency entirely by measuring the parent directly.

Share this Post on X Bluesky

What Is the Basic Container Query Syntax?

/* 1. Define a containment context on the parent */
.card-wrapper {
  container-type: inline-size;
  /* Optionally name it */
  container-name: card;
}

/* 2. Query the container inside the component */
@container (min-width: 400px) {
  .card {
    display: grid;
    grid-template-columns: auto 1fr;
  }
}

@container (min-width: 600px) {
  .card {
    gap: 2rem;
  }
}

Named containers

Name containers when you have nested containment contexts:

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

@container sidebar (min-width: 300px) {
  .widget { /* only applies when inside .sidebar */ }
}

@container main (min-width: 600px) {
  .widget { /* only applies when inside .main */ }
}
A laptop on a desk displaying a product website layout beside a phone
Photo by Igor Miske on Unsplash

How Do You Build a Truly Adaptive Card Component?

<div class="card-wrapper">
  <article class="card">
    <img class="card__image" src="..." alt="...">
    <div class="card__body">
      <h2 class="card__title">Article title</h2>
      <p class="card__desc">Description text...</p>
      <a class="card__cta">Read more</a>
    </div>
  </article>
</div>
.card-wrapper {
  container-type: inline-size;
}

/* Mobile-first: stacked layout */
.card {
  display: flex;
  flex-direction: column;
  gap: 1rem;
  padding: 1.25rem;
}

.card__image {
  width: 100%;
  aspect-ratio: 16/9;
  object-fit: cover;
  border-radius: 8px;
}

/* Wider container: side-by-side layout */
@container (min-width: 480px) {
  .card {
    flex-direction: row;
    align-items: flex-start;
  }

  .card__image {
    width: 180px;
    aspect-ratio: 1;
    flex-shrink: 0;
  }
}

/* Very wide container: larger typography */
@container (min-width: 700px) {
  .card__title { font-size: 1.5rem; }
  .card__desc  { font-size: 1rem; }
}

Now this card looks correct in a 1-column feed, a 3-column grid, and a narrow sidebar - with zero changes to the component markup.

A card component can look correct in a 1-column feed, a 3-column grid, and a narrow sidebar with zero changes to the markup.

Share this Post on X Bluesky

What Are the New Container Query Units?

CSS also introduces new units based on container size. There are six of them in the specification, and each maps directly to a dimension of the nearest containment context rather than the viewport, so an element sized in cqi scales with the box around it instead of the browser window. According to MDN's container size and style queries reference, cqi and cqb track the logical inline and block axes, which makes them the safer default in right-to-left or vertical writing modes, while cqw and cqh map to the simpler physical width and height that most developers reach for first.

UnitEquivalent to
cqi1% of inline size
cqb1% of block size
cqw1% of container width
cqh1% of container height
cqminSmaller of cqw/cqh
cqmaxLarger of cqw/cqh
.card__title {
  font-size: clamp(1rem, 4cqi, 2rem);
  /* scales with container width, not viewport */
}

Scaling type with cqi is one part of the picture; the other is choosing the right typeface and scale ratios so the typography reads well at every size the container allows. The web typography and font pairing guide on Art of Styleframe covers type scale construction, variable font setup, and the clamp()-based fluid typography approach that pairs directly with container query units.

What Are CSS Style Queries?

Style queries (newer than size queries, and with partial support in Chromium and Safari) let you query CSS custom property values:

@container style(--layout: horizontal) {
  .card {
    flex-direction: row;
  }
}

This enables "variant-driven" component styling from outside via CSS variables. The same custom property can steer a single value from inside the element, which is what CSS if() inline conditionals do, and if() can read the element's own property where a container query can only look at its ancestors.

A laptop, tablet, and phone side by side showing the same content across screen sizes
Photo by Firmbee.com on Unsplash

Why Does a Container Collapse to Zero Width?

This is the trap nobody warns you about. container-type: inline-size applies inline-size containment, which tells the browser the element's width must not depend on its contents. A side effect is that the element reports no intrinsic width at all. Wherever the layout already hands the box a width, you never notice. Wherever the box is supposed to size itself from what's inside it, there's nothing to size from.

I measured the same container, a div holding a heading and a sentence, in nine layout contexts, with and without container-type: inline-size. Headless Chromium 151.0.7922.34, Apple M1, 2026-10-16, a 1000px-wide page, widths from getBoundingClientRect():

Where the container sitsWithout container-typeWith inline-size
Block child1000px1000px
Grid track, 1fr1000px1000px
Flex item, flex: 11000px1000px
Table cell214px214px
Grid track, auto590px484px
Flex item, auto width214px0px
display: inline-block214px0px
float: left214px0px
position: absolute214px0px

In the four collapsed rows the height jumped from 40px to 192px, because the text inside wrapped word by word into a zero-width box. Nothing threw, nothing logged. The card simply became a thin vertical sliver, and the usual first guess, that the @container rule is wrong, sends you to the wrong place.

The auto grid track is the quieter case. The container didn't vanish, it just came out 106px narrower, because the auto track no longer got a width contribution from it.

Putting container-type: inline-size on a flex item with auto width, an inline-block, a float or an absolutely positioned box collapses it to 0px wide, because inline-size containment removes the intrinsic width those layouts size from.

Share this Post on X Bluesky

The fix is boring. Give the container a width the layout can use: flex: 1 or a flex-basis, a real grid track, width: 100%, or a wrapper that has one. Notice that flex: 1 and 1fr both worked above, which is the pattern. Anything that gets its width from the parent is safe, anything that asks the child how wide it wants to be isn't. So when a card inside a flex row suddenly disappears after you add container-type, check the flex item's width before you touch the query.

Does a Container Query Cost More Than a Media Query?

The common worry is that every container is a place the engine has to stop, measure and resume, so a page full of them must be slow. I wanted a number, and I wanted it for the situation people actually fear: a lot of cards, resized.

The test page is a grid of 300, 1,000 or 3,000 cards inside an iframe, so the iframe's width acts as the viewport for media queries and for layout. I switch it between 1200px and 780px. At 1200px the grid has four narrow columns and the cards stack; at 780px it has two wide columns and the cards go horizontal. Each sample is the time to apply the width and force style and layout, measured inside the page. Five variants run interleaved, one resize pair of each in turn, so a load spike lands on all of them instead of the one that happened to be running.

  • none: no query at all, the cost of the resize itself
  • media: a @media (max-width: 1000px) rule switches the card layout
  • perCard: every card wrapped in its own container-type: inline-size, with an @container rule
  • perCardNoQuery: the same N containers and no @container rule
  • single: one container, the grid, with an @container rule

Before comparing speed I made the script check that media, perCard and single produce identical boxes for the first and last card at both widths. A speed comparison between two layouts that render differently would be worthless. They matched at every size.

Median milliseconds for one resize to 780px plus one back to 1200px, run 1, with the ratio to the media-query version in brackets:

CardsnonemediaperCardperCardNoQuerysingle
3004.217.920.0 (1.12x)4.917.6 (0.98x)
1,00013.761.463.1 (1.03x)15.652.5 (0.86x)
3,00046.7170.8188.0 (1.10x)47.8170.5 (1.00x)

A second, independent run landed on 1.12x, 1.06x and 0.98x for one container per card, and 1.00x, 1.10x and 0.82x for a single container. The two runs disagree about which of the two container layouts is faster at 1,000 cards, which tells you what that last digit is worth: nothing.

Here's what I'd actually take from it. The cost of a media query, a container query per card and a single container all sit in the same band, between 0.82x and 1.12x of each other, and the sign flips between runs. I can't tell you container queries are faster, and I can't tell you they're slower. The expensive part of the resize is the layout switch itself, which is roughly three quarters of the time in every column, not the thing that decides to switch.

One direction did hold in both runs. Adding container-type to every card without writing a single @container rule cost between 2% and 17% more than no containment at all, in all six pairs. That's the "small layout cost" people mention, and it's small.

The caveats are not decoration. One engine, headless Chromium. One layout, a card grid, where the interesting work is in layout rather than style. The machine was shared with other jobs the whole time, with a load average above 25, so the absolute milliseconds are inflated and noisy. And I measured resize, not first paint or a long scroll, so I can't speak to those.

At 300, 1,000 and 3,000 cards, one container per card cost 0.98 to 1.12 times as much as an equivalent media query to resize in headless Chromium 151, and the sign flipped between two runs, so there's no measurable penalty either way.

Share this Post on X Bluesky

What Is the Browser Support and Fallback Story?

Container queries (size type) landed in all major browsers between mid-2022 and early 2023. Chrome 105 (August 2022) shipped first, Safari 16 followed in September 2022, and Firefox 110 arrived in February 2023. As of early 2026, global support sits at roughly 93% according to caniuse.com. That's high enough that you don't need to guard every query behind a feature check for new projects.

That said, 7% is still real users. Here's how to handle them without breaking layouts.

Chrome 105 shipped size-type container queries first in August 2022, Safari 16 followed a month later, and Firefox 110 closed the gap in February 2023, which is why global support crossed 93 percent by early 2026 according to caniuse tracking.

Share this Post on X Bluesky

Progressive enhancement with @supports:

/* Default layout - works everywhere */
.card {
  display: flex;
  flex-direction: column;
}

/* Only apply container query if supported */
@supports (container-type: inline-size) {
  .card-wrapper {
    container-type: inline-size;
  }

  @container (min-width: 480px) {
    .card {
      flex-direction: row;
    }
  }
}

The fallback stacks vertically - not ideal, but functional. Older browsers simply ignore the @supports block.

PostCSS plugin option: If you need broader compatibility, @csstools/postcss-container-queries compiles container queries into a JavaScript-driven polyfill at build time. I'd only reach for this on sites where IE 11 or older Android WebViews are genuine concerns - for most React or Astro apps, native browser support is sufficient.

Style queries: Chrome and Edge have supported @container style() for custom-property conditions since Chrome 111, Safari picked it up in 18.0, and Firefox followed in 151 (released May 19, 2026). All three engines now handle the custom-property form, so the old "Firefox is the holdout" caveat no longer applies. Two limits remain: Safari's support is partial (the document element can't be a container), and the range syntax inside style() is not in Safari yet. Keep style queries as progressive enhancement for anything that must work on older Firefox ESR builds, and put a @supports guard around them if you ship to those. For the cases where the condition lives on the same element, a plain custom property or a data- attribute selector is often simpler.

One practical tip: don't add container-type to every element by default. Apply it only to wrapper elements where you actually write @container queries. The measured cost of a bare containment context is small, as the next section shows, but the width collapse described there is a good reason on its own to keep the list short. And if you're still deciding between Grid and Flexbox inside those containers, check out the CSS Grid vs Flexbox comparison for a clear decision framework.

When Should You Use Container Queries vs Media Queries?

  • Container queries: Component-level adaptation (cards, widgets, sidebars)
  • Media queries: Page-level layout (number of columns, navigation pattern, font scale)
  • Both: A responsive page layout (media query) containing adaptive components (container queries)

Here's how to check whether a component is a good candidate for container queries:

  1. Check if the component gets reused in more than one layout context, like a sidebar and a main grid. If it doesn't, media queries alone are simpler.
  2. Check if the component's markup ever needs a variant class or prop just to handle placement. That's the strongest sign container queries will remove code.
  3. Check current browser support against your analytics. At roughly 93% global support in 2026, most audiences can drop the @supports fallback entirely.
  4. Check whether you need height-based queries. If so, add contain: size and an explicit height, since inline-size alone only tracks width.

Start adding container-type: inline-size to your component wrappers today. It's a low-risk addition and immediately unlocks better responsive behaviour across your component library. The pattern is straightforward: one property on the wrapper, one @container block per breakpoint you care about.

Where Can You Read More?

  • MDN: CSS Container Queries - complete specification, browser support, and named container reference
  • Can I use: CSS Container Queries - live browser support table
  • MDN: Container query length units - full reference for cqi, cqb, cqw, cqh, cqmin, cqmax

What Else Is Worth Reading?

  • CSS Grid vs Flexbox: How to Choose the Right Layout - container queries work best when you've already picked the right layout tool for your component structure
  • React Hooks pitfalls - if you're building React components with container-query-driven layouts, solid hook patterns keep your resize logic clean
  • shadcn/ui - copy-paste component library built on Tailwind CSS; container queries make its Card and layout components truly context-aware
  • Radix UI - unstyled accessible primitives you can style freely with container-query-driven CSS
  • Headless UI - Tailwind-first components from the Tailwind Labs team that pair naturally with container query layouts

Frequently Asked Questions

Do I still need media queries with container queries?
Yes - media queries handle viewport-level layout (page columns, navigation patterns), while container queries handle component-level adaptation. They complement each other.
What is browser support for container queries?
Container queries (size type) are supported in all major browsers since Chrome 105, Safari 16, and Firefox 110. Overall support is around 93% as of early 2026.
Can I query container height, not just width?
Yes. Use contain: size on the container and then @container (min-height: 400px) in your query. Height queries require the container to have an explicit height.
What is the difference between container-type: inline-size and container-type: size?
inline-size tracks only the container's inline axis (width in horizontal writing modes). size tracks both width and height but requires an explicit height on the container. Use inline-size for most component queries, it's the common case and imposes less layout cost than size.
Why does my container-type: inline-size element collapse to zero width?
inline-size containment removes the element's intrinsic width, so anything that sizes a box from its content sees nothing to measure. In headless Chromium 151 the same container measured 214px wide without container-type and 0px wide with it when it was an auto-width flex item, an inline-block, a float or an absolutely positioned box. Block children, 1fr grid tracks and flex: 1 items kept their width. Give the container an explicit width, flex-basis or grid track, or wrap it in an element that has one.
Are container queries slower than media queries?
Not by a margin I could measure. Resizing a grid of 300, 1,000 and 3,000 cards between a 1200px and a 780px viewport took 0.98 to 1.12 times as long with one container per card, and 0.82 to 1.10 times as long with a single container, compared with an equivalent media query, across two independent runs in headless Chromium 151. Adding container-type to every card with no query cost between 2 and 17 percent more than no containment at all.
Can I use container query units like cqw and cqh in CSS?
Yes. Container query units like cqw (1% of container width) and cqh (1% of container height) let you size elements relative to their container rather than the viewport. They work in any browser that supports container queries. Use cqw for fluid typography inside components without relying on viewport units.