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.

· · 9 min read

Updated: July 29, 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.

Quick take: Container queries let a component respond to its parent's size, not the viewport. Add container-type: inline-size to any wrapper element, then use @container (min-width: ...) to write context-aware styles inside it. Browser support is 93%+ as of 2026. Use them alongside media queries - not instead of them.

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. In our own projects, switching to container queries eliminated the need to maintain viewport-specific overrides for shared components.

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.

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.

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 (still experimental in some browsers) 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.

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

Browser Support and Fallbacks

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.

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, and Safari picked it up in 18.0. Firefox is the last holdout - Mozilla has it tracked for a 2026 release, but as of this update it still isn't shipping in stable Firefox. That means style queries remain the one piece of the container query spec you can't treat as universally available yet. Don't use them in production without an @supports (container-type: inline-size) guard combined with a check against the actual style-query condition, and keep them as progressive enhancement, not a load-bearing layout mechanism, until Firefox catches up.

One practical tip: don't add container-type to every element by default. Each containment context has a small layout cost. Apply it only to wrapper elements where you actually write @container queries. 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 to 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.

Further Reading

  • 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
  • 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.
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.