CSS Container Queries: The Complete Responsive Design Guide for US Developers

Quick Answer: CSS container queries let a component respond to the size of its parent container instead of the browser viewport. You set container-type: inline-size on the parent, then write an @container rule inside the child to change styles at specific container widths. This makes reusable components genuinely portable across sidebars, modals, cards, and full-width layouts without duplicating CSS.

Key Takeaways

• CSS container queries let a component respond to the size of its parent container, not the browser viewport, which makes reusable components truly portable across layouts.
• You only need two CSS declarations to get started: container-type: inline-size on the parent and an @container rule inside the child.
• Container queries and media queries are not competitors — use media queries for page-level layout and container queries for component-level responsiveness.
• Browser support in 2026 covers all modern evergreen browsers, including Chrome, Edge, Safari, and Firefox, so US teams can ship container queries without a polyfill for most audiences.
• The most common failure mode is forgetting to set container-type on the parent element, which silently disables every @container rule inside it.

About the Author

Written by Akash Soni, a web developer and technical writer at CodexCoach who has built and maintained responsive front-end interfaces for US-based client projects across WordPress, React, and custom CSS design systems.

CSS container queries responsive design guide is the missing piece most US front-end teams have been waiting for since component-based frameworks became the default. For years, you could build a perfect card component in isolation, drop it into a sidebar, and watch every media query break because the component was still listening to the viewport instead of its actual available space. Container queries fix that by letting each component respond to its own container — the element that wraps it — rather than the browser window.

This guide is written for intermediate CSS developers, UI engineers, and responsive designers who already understand media queries and now need to decide when container queries replace them, when they do not, and how to run both side-by-side in a production design system. We will cover the syntax, the browser support reality in 2026, three production-ready component examples, a side-by-side comparison table, and the migration decision framework US teams are actually using on real projects.

By the end, you will know exactly how to set up a container, write an @container rule, use container query units like cqw and cqi, and avoid the five mistakes that silently break container queries in production. Most importantly, you will have a clear rule for when to reach for container queries and when to leave your existing media queries alone.

What Are CSS Container Queries?

CSS container queries are a CSS feature that allows a component to apply styles based on the size of its nearest ancestor container, rather than the size of the viewport. You declare a containment context on a parent element using container-type, and then use the @container at-rule inside child elements to conditionally apply styles when that container meets certain size conditions. In practice, this means a card component can switch from a horizontal layout to a stacked layout when its container is narrow, regardless of how wide the browser window is.

The feature is built on three core pieces: container-type (which defines what the container can be queried on, such as inline-size), container-name (an optional label so you can target a specific ancestor when multiple containers are nested), and the @container at-rule itself (which contains the styles that apply when the condition matches). Container query length units like cqw, cqh, cqi, and cqb let you size elements relative to the container, similar to how vw and vh work relative to the viewport.

Container Queries vs Media Queries: The Core Difference

Media queries ask “how wide is the viewport?” Container queries ask “how wide is my parent container?” That single distinction changes how you architect responsive components. A media query on a card component forces that card to behave the same way everywhere it appears — in a narrow sidebar, a wide hero section, or a three-column grid. A container query lets the same card adapt independently in each of those contexts without any additional CSS.

How the @container Rule Works

The @container rule works like a media query but scoped to a container. You write @container (min-width: 400px) { ... } inside the child element, and those styles apply only when the nearest ancestor with a containment context is at least 400px wide. If no ancestor has container-type set, the rule is ignored — which is why forgetting that declaration is the most common bug developers hit.

What Is a Containment Context?

A containment context is any element that has container-type set to inline-size, size, or a named container value. Setting container-type: inline-size tells the browser to treat that element as a queryable container for its inline (horizontal) dimension, which is the right choice for almost all responsive component work. The size value queries both dimensions but requires the element to have a defined height, which is rarely practical for fluid layouts.

Why Container Queries Matter for Modern US Web Projects

US front-end teams spend a disproportionate amount of time fighting viewport-only responsive design. Media queries were built for a world of page-level layouts, not component libraries. When you ship a design system with reusable cards, dashboard widgets, navigation blocks, and CMS-driven content modules, media queries force you to either duplicate CSS per context or accept that components will look wrong in some placements. Container queries eliminate that trade-off.

The Problem With Viewport-Only Responsive Design

Consider a product card used in three places on the same page: a narrow sidebar, a two-column feature grid, and a full-width promotional banner. With media queries, all three instances share the same breakpoints because they all see the same viewport. The sidebar card looks cramped, the banner card looks sparse, and you end up writing context-specific overrides that defeat the purpose of a reusable component. Container queries let each instance respond to its own available width, so the component genuinely works everywhere without overrides.

Where Container Queries Save Development Time

Container queries reduce CSS duplication in design systems more than any feature since flexbox. Instead of writing separate responsive rules for sidebar cards, grid cards, and modal cards, you write one @container block that handles every context. For US teams maintaining large WordPress block themes or React component libraries, this translates directly into fewer style overrides, fewer visual regressions, and faster onboarding for new developers who no longer need to memorize which breakpoints apply where.

Browser Support in 2026: What US Teams Can Safely Ship

As of 2026, CSS container queries are supported in all modern evergreen browsers: Chrome, Edge, Safari, and Firefox. Support has been stable for several years, and the feature is now part of the baseline web platform. For US teams shipping to mobile-heavy audiences, the practical takeaway is that you can use container queries in production without a polyfill for the vast majority of users. Legacy browser fallbacks are still worth planning for if your analytics show meaningful traffic from older Safari or enterprise-locked browsers, but the default assumption in 2026 should be that container queries just work.

What Are CSS Container Queries?

CSS container queries are a native CSS feature that lets you style an element based on the size of its parent container rather than the viewport. You mark a parent with container-type, give it an optional container-name, and then use the @container at-rule to apply styles when that container meets a width, height, or style condition. For US developers building component-based UIs, this means a card, widget, or navigation block can adapt its internal layout no matter where it is placed on the page — a narrow sidebar, a wide hero, or a modal.

Container Queries vs Media Queries: The Core Difference

Media queries respond to the viewport — the browser window size. Container queries respond to the size of a containing element. That single distinction changes how you architect responsive components.

With media queries, a card component has no idea how much space it occupies. It only knows the screen width. If you place the same card in a 300px sidebar and a 900px main column, the card looks identical at a given viewport width — usually wrong in one of those contexts. You end up writing modifier classes like .card--sidebar or overriding styles from the parent, which fragments your CSS.

With container queries, the card itself defines breakpoints relative to its own container. Drop it into any slot and it adapts. No parent overrides, no duplicated CSS, no JavaScript measuring elements.

Rule of thumb: If a component’s layout should change based on the space it is given, use a container query. If the entire page layout should change based on device width, use a media query.

How the @container Rule Works

The @container at-rule works like @media, but it evaluates the nearest ancestor that has a containment context. You can query width, height, inline-size, block-size, aspect-ratio, orientation, and even custom properties (in browsers that support style queries).

Basic syntax:

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

/* 2. Query that container from the child */
@container card (min-width: 400px) {
  .card {
    display: grid;
    grid-template-columns: 120px 1fr;
    gap: 1rem;
  }
}

If you omit container-name, the query applies to the nearest ancestor with container-type set. Naming is useful when you have nested containers and want to target a specific one.

What Is a Containment Context?

A containment context is any element that has container-type set to inline-size, size, or normal. The value you choose determines what you can query and what performance trade-offs you accept.

• inline-size — establishes a query container for inline-axis (usually width) queries. This is the most common choice for responsive components. It does not require the element to have a fixed height.
• size — establishes a query container for both inline and block axes. Use this only when you need height-based queries, because it requires the element to have a definite size in both dimensions and can affect layout.
• normal — the element is not a query container for size queries, but it can still be a style query container. Use this when you only need style queries.

Containment also affects layout: an element with container-type: inline-size becomes a containment context, which means its children cannot affect its own size in the inline direction. In practice, this is what you want for reusable components — the parent sets the width, the child adapts.

Tip 1: Always set container-type: inline-size on a wrapper element, not directly on the component you are styling. This keeps the component’s own layout independent and avoids unexpected containment side effects.

Tip 2: Use container-name when you have nested containers (e.g., a dashboard widget inside a sidebar). Named containers prevent a child from accidentally querying the wrong ancestor.

Minimal Working Example: Responsive Card

Here is a complete, copy-paste example of a card that switches from a stacked layout to a horizontal layout when its container is at least 400px wide.

<div class="card-wrapper">
  <article class="card">
    <img src="thumbnail.jpg" alt="Project thumbnail">
    <div class="card-content">
      <h3>Project Title</h3>
      <p>Short description of the project.</p>
    </div>
  </article>
</div>

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

.card {
  display: flex;
  flex-direction: column;
  gap: 0.75rem;
}

@container card (min-width: 400px) {
  .card {
    flex-direction: row;
    align-items: center;
  }
  .card img {
    width: 120px;
    height: 120px;
    object-fit: cover;
  }
}
</style>

At container widths below 400px, the card stacks vertically. At 400px and above, it becomes a horizontal row with a fixed-size image. The same card can be dropped into a narrow sidebar or a wide content area and will adapt automatically — no media queries, no JavaScript.

This pattern is especially valuable in React and Vue, where components are meant to be reusable across different layout contexts. Instead of passing a layout prop or using CSS-in-JS conditionals, the component styles itself based on available space.

Why Container Queries Matter for Modern US Web Projects

US teams shipping design systems, dashboards, and CMS-driven sites face a recurring problem: viewport-based breakpoints cannot handle components that appear in multiple layout contexts. Container queries solve that problem natively, and in 2026 they are safe to use in production for the vast majority of US traffic.

The Problem With Viewport-Only Responsive Design

Media queries assume a direct relationship between viewport width and component width. That assumption breaks in at least four common scenarios:

• Sidebars and split layouts: A card in a 280px sidebar and the same card in a 700px main column need different internal layouts at the same viewport width. Media queries force you to write separate rules or add modifier classes.
• Modals and drawers: A modal might be 90vw on mobile and 600px on desktop. Components inside it need to respond to the modal’s width, not the viewport.
• Reusable cards in CMS-driven layouts: Editors can place the same card component in a 3-column grid, a 2-column grid, or a full-width feature. The component has no control over its placement.
• Dashboard widgets: A widget might be resized by the user via a drag handle. Media queries cannot respond to a resize that does not change the viewport.

In each case, developers end up with workarounds: JavaScript ResizeObserver logic, modifier classes, or duplicated CSS. Container queries eliminate the workaround.

Where Container Queries Save Development Time

Container queries reduce CSS duplication and make components truly portable. Consider a design system with a Card component used in three contexts: a homepage grid, a blog sidebar, and a related-posts section. With media queries, you might write:

/* Media query approach — fragmented */
.card { /* base styles */ }

@media (min-width: 768px) {
  .card { /* desktop styles */ }
}

/* Override for sidebar */
.sidebar .card {
  /* force stacked layout even on desktop */
}

/* Override for related posts */
.related-posts .card {
  /* force horizontal layout on desktop */
}

With container queries, the component owns its responsive logic:

/* Container query approach — self-contained */
.card-wrapper {
  container-type: inline-size;
}

.card { /* base stacked layout */ }

@container (min-width: 400px) {
  .card { /* horizontal layout */ }
}

No parent overrides. No modifier classes. The component adapts to whatever space it is given. For US teams maintaining large design systems, this can cut responsive CSS by 30–50% in component-heavy codebases.

Tip 3: When migrating an existing component to container queries, start with the smallest reusable unit — usually a card, list item, or widget. Wrap it in a container context, move its media queries to @container rules, and test it in every layout slot it appears in. Do not migrate the entire page layout at once.

Browser Support in 2026: What US Teams Can Safely Ship

As of early 2026, CSS container queries are supported in all major browsers:

• Chrome / Edge: Supported since version 105 (August 2022). Full support for size queries, named containers, and style queries in recent versions.
• Safari: Supported since Safari 16.0 (September 2022). Style queries and some advanced features may lag slightly; check caniuse.com for the latest.
• Firefox: Supported since Firefox 110 (February 2023). Full support for size and style queries in current versions.

Global support is above 95% according to caniuse.com. For US audiences, where modern browser adoption is even higher, container queries are safe to ship without a polyfill for most projects. The exception is if you must support older enterprise environments or legacy embedded browsers — in that case, use a progressive enhancement approach: write media-query fallbacks first, then layer container queries on top.

When to use a polyfill: The most common polyfill is container-query-polyfill from Google Chrome Labs. It is only necessary if you need to support browsers older than the versions listed above. For most US teams in 2026, the polyfill adds unnecessary JavaScript weight and is not recommended. Instead, use @supports (container-type: inline-size) to provide a graceful fallback.

/* Fallback for browsers without container query support */
.card { /* mobile-first stacked layout */ }

@supports (container-type: inline-size) {
  .card-wrapper {
    container-type: inline-size;
  }
  @container (min-width: 400px) {
    .card { /* horizontal layout */ }
  }
}

This approach ensures older browsers get a usable layout while modern browsers get the enhanced responsive behavior.

Performance considerations: Container queries are implemented natively in the browser’s style engine and do not require JavaScript. They are generally as performant as media queries. However, be mindful of containment: setting container-type: size on many elements can trigger additional layout calculations. For most US teams shipping to mobile-heavy audiences, container-type: inline-size is the right default — it has minimal performance overhead and covers the vast majority of responsive component needs.

For teams using React, Vue, or Svelte, container queries also reduce the need for JavaScript-based resize observers, which improves runtime performance and reduces bundle size. A component that previously needed a useResizeObserver hook can now be pure CSS.

How to Use CSS Container Queries: Step-by-Step

CSS container queries let you style elements based on the size of their parent container, not the viewport. This is the fundamental shift that makes components truly responsive to their context. Below is a complete, copy‑paste walkthrough from setup to testing, with the exact syntax and gotchas you need to ship container queries in production today.

Step 1: Set Up the Container With container-type

Before you can query a container, you must declare it as a query container. The container-type property does this. It tells the browser to establish a containment context for size queries.

/* The parent element becomes a container */
.card-wrapper {
  container-type: inline-size;
}

There are three values for container-type:

• inline-size – Enables size queries on the inline axis (width in horizontal writing modes). This is the most common choice for responsive components like cards, widgets, and navigation.
• size – Enables size queries on both inline and block axes. Use this only when you need to query height as well as width, and when the container’s size is independent of its content (e.g., a fixed‑height dashboard panel).
• normal – The default. The element is not a query container for size queries, but it can still be a style query container. You rarely need to set this explicitly.

Tip 1: Prefer inline-size unless you have a specific need for block‑axis queries. Using size imposes stricter containment that can break layouts if the container’s height depends on its children.

Tip 2: Apply container-type to a wrapper element, not directly to the component itself, when you want the component to respond to its parent’s width. This avoids self‑referential loops and keeps your CSS predictable.

Step 2: Name the Container With container-name (Optional but Useful)

When you have multiple nested containers, naming them lets you target a specific ancestor. Without a name, @container rules match the nearest ancestor container that meets the condition.

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

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

Then you can write:

@container sidebar (min-width: 400px) {
  .widget { /* styles when sidebar is at least 400px wide */ }
}

Tip 3: Use names when a component might be placed inside different containers and you need different styles for each context. For example, the same card component might appear in a narrow sidebar and a wide main column.

Step 3: Write the @container Rule

The @container at‑rule works like a media query but evaluates the size of the nearest ancestor container (or a named container).

/* Query the nearest container */
@container (min-width: 500px) {
  .card {
    display: flex;
    gap: 1rem;
  }
}

/* Query a named container */
@container main (min-width: 800px) {
  .card {
    grid-template-columns: 1fr 2fr;
  }
}

You can use min-width, max-width, min-height, max-height, and range syntax like (400px <= width <= 800px). Conditions can be combined with and, or, and not.

Tip 4: Container queries are evaluated based on the container’s content box, not its border box. Account for padding if your design depends on precise measurements.

Step 4: Use Container Query Units (cqw, cqh, cqi, cqb)

Container query length units are relative to the query container’s dimensions. They are the secret to fluid typography and spacing that scales with the component, not the viewport.

• cqw – 1% of the container’s width
• cqh – 1% of the container’s height
• cqi – 1% of the container’s inline size
• cqb – 1% of the container’s block size
• cqmin – the smaller of cqi or cqb
• cqmax – the larger of cqi or cqb

.card-title {
  font-size: clamp(1rem, 4cqi, 1.5rem);
}

.card {
  padding: 2cqi;
}

These units are especially powerful for fluid type and spacing within components. Unlike vw, they respect the component’s context, so a card in a narrow sidebar won’t have absurdly large text.

Tip 5: Use cqi instead of cqw for horizontal writing modes to be writing‑mode agnostic. For vertical writing modes, cqb becomes the inline axis.

Step 5: Test Across Container Sizes

Testing container queries requires simulating different container widths, not viewport widths. Modern browser DevTools make this straightforward.

In Chrome and Edge DevTools:

1. Inspect an element that is a query container.
2. Look for a small “container” badge next to the element in the Elements panel.
3. Click the badge to see the container’s current size and toggle a visual overlay.
4. Use the Styles pane to see which @container rules are active.

In Firefox, the Inspector shows a container icon and allows resizing the container directly in the responsive design mode.

For automated testing, you can use Playwright or Puppeteer to set the width of a container element and assert computed styles. Example with Playwright:

await page.setViewportSize({ width: 1200, height: 800 });
await page.locator('.card-wrapper').evaluate(el => el.style.width = '300px');
const fontSize = await page.locator('.card-title').evaluate(el => getComputedStyle(el).fontSize);
expect(fontSize).toBe('16px');

Accessibility and fallback: Container queries are supported in all modern browsers (Chrome 105+, Safari 16+, Firefox 110+). For older browsers, the styles inside @container are ignored, so your component will fall back to the base styles. Always design mobile‑first base styles that work without container queries, then enhance with them. Do not rely on container queries for critical layout that would break accessibility if missing.

Container Queries vs Media Queries: Side-by-Side Comparison

Media queries have been the backbone of responsive design for over a decade. Container queries are not a replacement—they solve a different problem. Understanding when to use each is the key to a maintainable 2026 codebase.

When to Use Container Queries

Use container queries when a component’s layout should adapt to the space it is given, regardless of the viewport. This is the defining characteristic of a truly reusable component.

Tip 1: If you find yourself writing multiple media queries to adjust a component for different page zones (e.g., sidebar vs main content), that’s a clear signal to switch to container queries.

Example: A product card that displays as a vertical stack in a narrow sidebar, a horizontal row in a wide main column, and a grid item in a full‑width section. With media queries, you’d need to know the viewport width at which each layout change occurs—and that changes if the sidebar width changes. With container queries, the card just responds to its own width.

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

.product-card__inner {
  display: grid;
  gap: 1rem;
}

@container (min-width: 400px) {
  .product-card__inner {
    grid-template-columns: 120px 1fr;
  }
}

@container (min-width: 700px) {
  .product-card__inner {
    grid-template-columns: 200px 1fr;
    gap: 2rem;
  }
}

When to Stick With Media Queries

Media queries remain the right tool for page‑level layout and global design decisions. They are simpler, have no containment side effects, and are universally supported.

Tip 2: Use media queries for anything that depends on the viewport as a whole: overall grid structure, navigation toggles, font‑size scaling for readability, and print styles. Also use them for feature detection via @media (hover: hover) or @media (prefers-reduced-motion).

Example: A website’s main layout might switch from a single column to a two‑column layout at 768px. That’s a page‑level decision—media query territory.

Using Both Together in One Codebase

The most robust approach in 2026 is a hybrid: media queries for macro layout, container queries for micro layout. This keeps your global breakpoints stable while making components truly portable.

Tip 3: Establish a clear rule: media queries control the page skeleton; container queries control the components within that skeleton. Document this in your design system.

Example hybrid setup:

/* Page-level layout with media queries */
.layout {
  display: grid;
  grid-template-columns: 1fr;
}

@media (min-width: 1024px) {
  .layout {
    grid-template-columns: 240px 1fr;
  }
}

/* Component-level with container queries */
.sidebar {
  container-type: inline-size;
}

.widget {
  display: grid;
  gap: 0.5rem;
}

@container (min-width: 200px) {
  .widget {
    grid-template-columns: auto 1fr;
    align-items: center;
  }
}

Common pitfalls when mixing both:

• Over‑nesting containers: Too many containers can make it hard to reason about which container a query resolves to. Name containers when nesting more than two levels deep.
• Forgetting containment side effects: container-type: inline-size applies layout containment, which can affect margin collapsing and percentage‑based sizing. Test thoroughly.
• Using container queries for global layout: This leads to fragile layouts that break when the container’s context changes. Reserve them for components.
• Assuming container queries replace media queries: They don’t. Media queries still handle viewport‑dependent features like prefers-color-scheme and orientation.

By following this hybrid model, US development teams can migrate incrementally: start by adding container queries to new components, then refactor existing components one by one. Your media queries stay in place for page structure, and your components become context‑aware and reusable across any layout.

Real-World Examples: Container Queries in Production Components

Container queries are not a theoretical upgrade. They solve specific layout problems that US developers hit every week when building component-driven interfaces. The three examples below are copy-ready and cover the patterns you are most likely to ship: a product card in a grid, a dashboard widget in a resizable panel, and a navigation bar embedded in a sidebar. For each one, I show the container query implementation, the equivalent media query version, and why the container query version is cleaner.

Example 1: A Product Card That Adapts Inside Any Grid

This is the canonical container query use case. A product card should change layout based on the width of its parent grid cell, not the viewport. On a wide desktop, the same card might appear in a 4-column grid, a 2-column grid, or a narrow sidebar. Media queries cannot know that context.

HTML:

<div class="product-grid">
  <article class="product-card">
    <img src="headphones.jpg" alt="Wireless headphones">
    <div class="product-card__content">
      <h3>Studio Headphones</h3>
      <p>Noise-cancelling, 40-hour battery.</p>
      <span class="price">$199</span>
    </div>
  </article>
</div>

CSS with container queries:

.product-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
  gap: 1.5rem;
}

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

/* Default: stacked layout */
.product-card__content {
  padding: 1rem;
}

/* When the card container is wider than 400px, switch to horizontal */
@container card (min-width: 400px) {
  .product-card {
    display: flex;
    gap: 1rem;
    align-items: center;
  }
  .product-card img {
    width: 120px;
    height: 120px;
    object-fit: cover;
  }
  .product-card__content {
    padding: 0.5rem 0;
  }
}

The media query equivalent:

/* This only works if you know the grid context at every breakpoint */
@media (min-width: 768px) {
  .product-card {
    display: flex;
    gap: 1rem;
  }
}
/* But what if the card is in a 2-col grid on desktop? Or a sidebar? */
/* You end up with modifier classes: .product-card--horizontal */

The media query version forces you to either create modifier classes or accept that the card will look wrong in some contexts. The container query version adapts automatically. In a 4-column grid on a 1440px screen, each card is roughly 320px wide, so it stays stacked. In a 2-column grid, each card is roughly 680px wide, so it switches to horizontal. No JavaScript, no extra classes.

React integration note: In React, you do not need to change your component structure. The container query lives entirely in CSS. If you use CSS Modules or styled-components, define the container-type on the card wrapper and the @container rule in the same stylesheet. For styled-components, use the css helper inside a media-like block. Example:

import styled from 'styled-components';

const Card = styled.article`
  container-type: inline-size;
  container-name: card;
  @container card (min-width: 400px) {
    display: flex;
    gap: 1rem;
  }
`;

Vue integration note: In Vue SFCs, add container-type: inline-size to the card’s scoped style. The @container rule works identically. No changes to your template logic.

WordPress block theme note: If you are building a block theme, add the container query CSS to your theme’s theme.json or a custom stylesheet enqueued in functions.php. The card block can be a reusable pattern. The container query will apply wherever the pattern is placed, whether in a query loop or a sidebar.

DevTools reference: In Chrome DevTools, select the card element. In the Elements panel, you will see a container badge next to the element that has container-type set. Hovering over it shows the container name and size. You can also use the Layout pane to toggle container query overlays, which highlight the container boundaries on the page.

Example 2: A Dashboard Widget for a US SaaS Admin Panel

US SaaS admin panels often let users resize dashboard panels or rearrange them in a grid. A widget that shows a chart and a summary should adapt its layout based on the panel width, not the browser width. This is where container queries shine.

HTML:

<div class="dashboard">
  <section class="widget">
    <header>
      <h3>Monthly Recurring Revenue</h3>
      <span class="badge">+12%</span>
    </header>
    <div class="widget__body">
      <canvas id="mrr-chart"></canvas>
      <ul class="metrics">
        <li><strong>$48,200</strong> MRR</li>
        <li><strong>312</strong> Active subs</li>
      </ul>
    </div>
  </section>
</div>

CSS with container queries:

.dashboard {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: 1rem;
}

.widget {
  container-type: inline-size;
  container-name: widget;
  border: 1px solid #e5e7eb;
  border-radius: 8px;
  padding: 1rem;
}

.widget__body {
  display: grid;
  gap: 1rem;
}

/* Narrow widget: stack chart and metrics */
@container widget (max-width: 400px) {
  .widget__body {
    grid-template-columns: 1fr;
  }
  .metrics {
    display: flex;
    gap: 1rem;
    justify-content: space-between;
  }
}

/* Wide widget: side-by-side chart and metrics */
@container widget (min-width: 401px) {
  .widget__body {
    grid-template-columns: 1fr 180px;
  }
  .metrics {
    display: flex;
    flex-direction: column;
    gap: 0.5rem;
  }
}

Why media queries fail here: A user on a 1440px monitor might have the widget in a narrow column. A media query at min-width: 1200px would trigger the wide layout even though the widget is only 320px wide. The container query checks the widget’s actual width, so the layout is always correct.

React integration note: If you use a drag-and-drop dashboard library like react-grid-layout, the widget width changes dynamically. Container queries respond automatically without re-rendering the component. This reduces JavaScript overhead and avoids layout thrashing.

Vue integration note: In Vue, you can bind the container query CSS to a scoped style block. The widget component does not need to know its parent width. It just works.

WordPress block theme note: For custom admin panels built with WordPress, you can use container queries in your plugin’s CSS. The widget can be a Gutenberg block. The container-type goes on the block wrapper.

DevTools reference: In Firefox DevTools, the Inspector shows a container badge. You can click it to see the container’s size and name. Firefox also has a dedicated Container Queries panel that lists all containers on the page.

Example 3: A Navigation Bar That Collapses Inside a Sidebar

Navigation is usually handled with media queries, but when a nav is placed inside a sidebar or a narrow panel, media queries break. This example shows a nav that collapses to a hamburger menu when its container is narrow, regardless of viewport width.

HTML:

<nav class="sidebar-nav">
  <button class="nav-toggle" aria-expanded="false">Menu</button>
  <ul class="nav-list">
    <li><a href="/dashboard">Dashboard</a></li>
    <li><a href="/projects">Projects</a></li>
    <li><a href="/settings">Settings</a></li>
  </ul>
</nav>

CSS with container queries:

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

.nav-toggle {
  display: none;
}

.nav-list {
  display: flex;
  gap: 1rem;
  list-style: none;
  padding: 0;
}

/* When container is narrower than 300px, collapse to hamburger */
@container nav (max-width: 300px) {
  .nav-toggle {
    display: block;
  }
  .nav-list {
    display: none;
    flex-direction: column;
  }
  .nav-list.is-open {
    display: flex;
  }
}

Why this matters: A sidebar nav might be 250px wide on a desktop, while the main nav at the top of the page is 1200px wide. With media queries, you would need separate classes or a JavaScript resize observer. With container queries, the same component adapts to its container.

React integration note: The toggle state can be managed with useState. The container query handles the visual collapse. This keeps the logic simple.

Vue integration note: Use a ref for the toggle and a v-if for the list. The container query CSS remains in the style block.

WordPress block theme note: For a navigation block, you can add container-type to the nav wrapper. The core navigation block already has responsive behavior, but container queries give you finer control.

DevTools reference: In Chrome DevTools, you can simulate container sizes by editing the container’s width in the Styles pane. The @container rules will update live. This is useful for testing breakpoints without resizing the browser.

Tip 1: Always name your containers. Without a name, @container (min-width: 400px) will match the nearest ancestor container, which may not be the one you intended. Naming prevents unexpected matches when you nest components.

Tip 2: Use container-type: inline-size for most components. It only tracks the inline (horizontal) dimension, which is what you need for responsive layouts. container-type: size tracks both dimensions and can cause performance issues if used excessively.

Tip 3: When migrating from media queries, start with one component at a time. Do not rewrite your entire design system at once. Pick a component that appears in multiple contexts (like a card) and convert it first. Measure the impact on your CSS bundle size and runtime performance.

Common Mistakes Developers Make With Container Queries

Container queries are powerful, but they have sharp edges. These are the five mistakes I see most often in code reviews and production audits. Each one includes what it looks like in the browser, why developers make it, and how to fix it.

Forgetting to Set container-type

What it looks like: You write an @container rule, but nothing happens. DevTools shows no container badge. The layout stays the same at all sizes.

Why developers make it: The @container syntax looks similar to @media. Developers assume the browser automatically knows which element is the container. It does not. You must explicitly declare a containment context.

Broken pattern:

.card {
  /* no container-type */
}

@container (min-width: 400px) {
  .card { display: flex; }
}

Fixed pattern:

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

@container (min-width: 400px) {
  .card { display: flex; }
}

Debugging tip: In Chrome DevTools, select the element you expect to be a container. Look for the container badge in the Elements panel. If it is missing, check the computed styles for container-type. Also check that no ancestor has display: none or content-visibility: hidden, which can disable containment.

Applying container-type to the Wrong Element

What it looks like: The container query triggers at unexpected sizes. For example, a card switches to horizontal layout when the viewport is wide, but the card itself is still narrow.

Why developers make it: It is easy to put container-type on a parent wrapper instead of the component itself. If the wrapper is full-width, the container query is effectively a media query.

Broken pattern:

.grid-wrapper {
  container-type: inline-size; /* wrong: this is full-width */
}

.card {
  /* card is inside the wrapper */
}

@container (min-width: 400px) {
  .card { display: flex; }
}

Fixed pattern:

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

@container (min-width: 400px) {
  .card { display: flex; }
}

Debugging tip: Use the Layout pane in Chrome DevTools to toggle container overlays. The overlay highlights the element that is acting as the container. If the highlight is on a full-width wrapper, you have applied it to the wrong element.

Nesting Containers Without Clear Naming

What it looks like: An @container rule matches an ancestor container you did not intend. For example, a button inside a card matches the card’s container instead of its own.

Why developers make it: When containers are nested, the browser uses the nearest ancestor container that matches the query. Without names, it is hard to predict which one will match.

Broken pattern:

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

@container (min-width: 200px) {
  .button { font-size: 1.2rem; }
}
/* This might match the card, not the button, if the button is inside the card */

Fixed pattern:

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

@container button (min-width: 200px) {
  .button { font-size: 1.2rem; }
}

Debugging tip: In Firefox DevTools, the Container Queries panel lists all containers and their names. You can see which container is being used for each query. If a query is matching the wrong container, add a name.

Mixing Container Query Units With Viewport Units Incorrectly

What it looks like: Text or spacing scales with the viewport instead of the container. For example, a heading inside a narrow card becomes huge on a wide screen.

Why developers make it: Container query units like cqw, cqh, cqi, and cqb are new. Developers sometimes use vw out of habit, which is viewport-relative, not container-relative.

Broken pattern:

.card h3 {
  font-size: 5vw; /* scales with viewport, not card */
}

Fixed pattern:

.card {
  container-type: inline-size;
}
.card h3 {
  font-size: 5cqi; /* scales with card's inline size */
}

Debugging tip: In Chrome DevTools, inspect the computed font-size. If it changes when you resize the browser but not when you resize the container, you are using the wrong unit. Use the container query units reference in the CSS spec to confirm the correct unit.

Ignoring Fallback Behavior for Older Browsers

What it looks like: In older browsers (Safari before 16, Firefox before 110, Chrome before 105), the container query rules are ignored. The component renders in its default state, which may be broken or unstyled.

Why developers make it: Container queries are now widely supported, but some US enterprise environments still run older browsers. If you do not provide a fallback, those users see a degraded experience.

Broken pattern:

.card {
  container-type: inline-size;
  display: block; /* default stacked layout */
}
@container (min-width: 400px) {
  .card { display: flex; }
}
/* In older browsers, the card is always stacked, even on wide screens */

Fixed pattern:

.card {
  container-type: inline-size;
  display: block;
}

/* Fallback for browsers that do not support container queries */
@supports not (container-type: inline-size) {
  @media (min-width: 768px) {
    .card { display: flex; }
  }
}

@container (min-width: 400px) {
  .card { display: flex; }
}

Debugging tip: Use @supports to test for container query support. In DevTools, you can emulate older browsers by disabling container queries in the Rendering panel. Chrome has a setting to disable individual CSS features for testing.

Tip 4: Use @supports (container-type: inline-size) to detect support. This is more reliable than user-agent sniffing. It also lets you load a polyfill conditionally if you need one.

Tip 5: When debugging container queries, start with the container element. Verify that container-type is set and that the element has a defined width. If the container has width: auto and no explicit size, the container query may not behave as expected.

Best Practices for Container Queries in 2026

Container queries are now supported across all major browsers, but shipping them in a production design system is a different problem from writing a demo. The teams getting the most out of CSS container queries in 2026 follow five rules that separate maintainable component libraries from one-off experiments. Each rule below is written to be applied in a real US product team codebase, not a CodePen.

Tip 1: Name Containers in Design Systems

Anonymous containers work fine for a single component, but the moment two nested wrappers both declare container-type: inline-size, an unnamed @container query resolves to the nearest ancestor. In a card grid inside a dashboard panel inside a sidebar, that nearest ancestor is rarely the one you meant. Naming containers removes the ambiguity permanently.

/* Design system token: name every container wrapper */
.card-shell {
  container-type: inline-size;
  container-name: card;
}

.panel-shell {
  container-type: inline-size;
  container-name: panel;
}

/* Query the card, not whatever wrapper happens to be closest */
@container card (min-width: 30rem) {
  .card__body {
    display: grid;
    grid-template-columns: 12rem 1fr;
    gap: 1.5rem;
  }
}

@container panel (min-width: 48rem) {
  .panel__chart {
    grid-column: span 2;
  }
}

Naming convention that scales: prefix the container name with the component family (card, panel, nav, widget) and never reuse a name for two different containment contexts. When a junior developer greps for container-name: card, they should find exactly one definition in the codebase.

Tip 2: Keep Containment Scoped to Layout Wrappers

container-type: inline-size establishes an inline-size containment context. It also creates a new formatting context, which means applying it to a leaf element (a paragraph, a button, an icon wrapper) can change how that element sizes and wraps. Apply containment to the layout wrapper, not the content inside it.

/* Wrong: containment on a text element changes its intrinsic sizing */
.card__title {
  container-type: inline-size; /* don't */
}

/* Right: containment on the wrapper that defines the available space */
.card {
  container-type: inline-size;
}

.card__title {
  font-size: clamp(1rem, 4cqi, 1.5rem);
}

Rule of thumb for US teams shipping component libraries: every component gets one container wrapper at its root. Child elements query that wrapper. If you find yourself adding a second container-type inside the same component, you probably want a nested subcomponent with its own root instead.

Tip 3: Prefer Logical Properties With Container Units

Container query length units (cqw, cqh, cqi, cqb, cqmin, cqmax) resolve against the nearest container. Pairing them with logical properties (inline-size, block-size, margin-inline, padding-block) means your component behaves correctly when the writing direction or orientation changes, without a second stylesheet.

.widget {
  container-type: inline-size;
  padding-block: 1rem;
  padding-inline: clamp(0.75rem, 2cqi, 2rem);
}

.widget__metric {
  font-size: clamp(1.5rem, 6cqi, 3rem);
  line-height: 1.1;
}

.widget__label {
  font-size: clamp(0.75rem, 2cqi, 0.875rem);
  letter-spacing: 0.02em;
}

Why this matters in practice: US teams frequently ship the same component to a left-to-right marketing site and an RTL localized product. Logical properties plus container units means the widget’s typography scales with its container width in both directions, and you avoid a hardcoded padding-left that breaks in Arabic or Hebrew locales.

Tip 4: Document Container Breakpoints in Your Style Guide

The single biggest failure mode in multi-developer teams is breakpoint drift: one developer queries at 30rem, another at 32rem, a third at 480px. Six months later the design system has fifteen near-identical breakpoints and nobody knows which is canonical. Standardize container breakpoints as design tokens and document them next to your spacing and color scales.

:root {
  /* Container breakpoints — canonical set, do not add ad hoc values */
  --cq-xs: 20rem;  /* 320px  — mobile card */
  --cq-sm: 30rem;  /* 480px  — two-column card */
  --cq-md: 48rem;  /* 768px  — dashboard panel */
  --cq-lg: 64rem;  /* 1024px — full-width widget */
  --cq-xl: 80rem;  /* 1280px — split navigation */
}

@container card (min-width: 30rem) { /* --cq-sm */ }
@container panel (min-width: 48rem) { /* --cq-md */ }
@container nav (min-width: 80rem) { /* --cq-xl */ }

Document each breakpoint with a one-line rationale: what layout change happens at that width and why. A style guide entry like “--cq-sm (30rem): card switches from stacked to side-by-side image and body” tells the next developer whether their new component should reuse that token or genuinely needs a new one.

Tip 5: Test With Real Content, Not Lorem Ipsum

Container queries respond to the actual inline size of the container, which depends on content. A card that looks perfect with three words of placeholder text will break when a real product name runs to forty characters, or when a German translation doubles the string length. Test every container-query component with the longest realistic content your product will ship.

/* Defensive pattern: allow text to wrap rather than overflow the container */
.card__title {
  overflow-wrap: anywhere;
  hyphens: auto;
  min-inline-size: 0; /* flex/grid children default to min-content */
}

/* Test at the narrowest container width with the longest string */
@container card (max-width: 19.99rem) {
  .card__title {
    font-size: 1rem;
    line-height: 1.3;
  }
}

Practical test matrix for US teams: for each container-query component, verify at the narrowest container width (320px), the breakpoint boundary (just above and just below --cq-sm), and the widest container width. Use the longest product name, the longest error message, and the longest translated string in your locale set. If it holds at all three, it will hold in production.

Tools, Resources, and a Quick-Start Checklist

Container queries have first-class tooling in 2026, but the DevTools experience differs across Chrome, Firefox, and Safari. This section covers what each browser inspector gives you, the reference links worth bookmarking, and a seven-item checklist to run before any container-query component ships.

Browser DevTools Features for Container Queries

Each major browser exposes container query inspection differently. Knowing what to look for saves hours of debugging.

• Chrome DevTools: The Elements panel shows a container badge on any element with container-type set. Clicking the badge reveals the container’s resolved inline size and name. The Styles pane displays which @container rule is currently matching, and the Layout panel lets you toggle container query overlays to highlight containment contexts on the page.
• Firefox DevTools: The Inspector marks container elements with a container tag and shows the active container query in the Rules panel. Firefox’s responsive design mode lets you resize the container independently of the viewport, which is the fastest way to test breakpoint boundaries without resizing the whole browser window.
• Safari Web Inspector: Safari displays container query matches in the Styles sidebar and supports containment highlighting. Safari’s implementation is strict about container-name matching, so if a query silently fails, check that the name matches exactly — Safari will not fall back to an unnamed ancestor when a name is specified.

Cross-browser debugging tip: if a container query works in Chrome but not Safari, the most common cause is a name mismatch or a missing container-type on the intended ancestor. Safari’s stricter resolution surfaces these bugs earlier, which is why it is worth testing there first.

Useful Reference Links

• MDN Web Docs — CSS Container Queries: the canonical reference for syntax, units, and browser behavior. Bookmark the container query length units section separately.
• W3C CSS Containment Module Level 3: the specification itself. Read the containment context and query resolution sections if you need to resolve an edge case, particularly around nested named containers.
• Can I Use — CSS Container Queries: current browser support table. As of 2026, support is baseline across Chrome, Firefox, Safari, and Edge; check here before adding a polyfill or fallback.
• MDN — Container Size and Style Queries: covers @container style() queries, which let components respond to custom property values rather than size alone.

Container Query Quick-Start Checklist

Run through these seven items before merging any container-query component. Each one maps to a failure mode that has shipped to production on real teams.

1. Container is named. The wrapper has both container-type: inline-size and a container-name that is unique in the component tree. Grep the codebase for the name to confirm there is only one definition.
2. Containment is on the layout wrapper only. No leaf text or icon element has container-type set. The component has exactly one containment context at its root.
3. Breakpoints use design tokens. Every @container query references a --cq-* token, not a hardcoded rem or px value. No ad hoc breakpoints were introduced.
4. Container units are paired with logical properties. Sizing uses cqi/cqb and inline-size/block-size, not cqw/cqh with physical properties, unless there is a documented reason.
5. Tested at boundary widths. The component was checked just above and just below each breakpoint token, plus at 320px and the widest realistic container.
6. Tested with real content. Longest product name, longest error string, and longest translated string all render without overflow or layout shift.
7. Verified in all three engines. The component was inspected in Chrome, Firefox, and Safari DevTools, and the matching @container rule is visible in each. Any silent failure is resolved, not worked around.

Teams that run this checklist before merge report far fewer container-query regressions than teams that debug after release. The checklist takes under ten minutes per component and catches the four most common failure modes: unnamed containers, containment on leaf elements, breakpoint drift, and content overflow.

Conclusion: When Should You Adopt Container Queries?

The decision to adopt container queries is not about whether they are better than media queries—it is about whether your components need to respond to their own available space rather than the viewport. For most US development teams in 2026, the answer is: adopt container queries for reusable components that appear in multiple layout contexts, and keep media queries for page-level layout and global breakpoints. This hybrid approach delivers the best maintainability and performance without forcing a full rewrite of your existing responsive system.

The One Rule to Remember

If a component’s layout should change based on the width of its parent container—not the browser window—use a container query. If it should change based on the overall device size, use a media query. That single rule prevents the most common mistakes and keeps your CSS predictable.

Your Next Step

Audit one component library this week. Pick a card component that currently uses media queries and convert it to a container query. Measure the before-and-after in terms of code complexity and visual consistency across your app. Then expand to dashboard widgets and navigation patterns. For more hands-on CSS and responsive design guides, explore our complete container queries guide and our modern CSS layout techniques article.

Tip 1: Start with a single component, not the whole design system. Converting one card component gives you immediate insight into container query behavior and builds team confidence before scaling.

Common Mistakes When Using CSS Container Queries

Container queries solve a problem flexbox and media queries never could, but they introduce failure modes that are easy to miss in code review. These are the five mistakes I see most often in production codebases, and how to avoid each one.

1. Forgetting to declare container-type on the parent

What happens: You write @container (min-width: 400px) { ... }, save, and nothing changes. The query silently matches nothing because the browser has no containment context to evaluate against.

Why people make it: The @container at-rule syntax looks self-contained. It reads as if the query itself defines the context. It does not — the context must exist on an ancestor element first.

How to avoid it: Always pair the query with a declared container. Use container-type: inline-size for layout-driven queries (the common case) or container-type: size when you also need to query block size.

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

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

2. Using container-type: size when you only need inline-size

What happens: Elements collapse to zero height, or scrollbars appear unexpectedly. size containment forces the browser to ignore the element’s intrinsic block size, which breaks auto-height layouts.

Why people make it: size sounds more capable than inline-size, so developers reach for it first. In practice, roughly 90% of responsive component work only needs width-based queries.

How to avoid it: Default to container-type: inline-size. Only use size when you have explicitly set a fixed height on the container and genuinely need block-axis queries.

3. Nesting containers without naming them

What happens: A query intended for the outer container matches the inner one instead. The component renders at the wrong breakpoint and the bug only shows up in specific page compositions.

Why people make it: Unnamed containers resolve to the nearest ancestor with a containment context. When you nest a card inside a sidebar inside a grid, “nearest ancestor” is rarely what you meant.

How to avoid it: Give every container a container-name and reference it explicitly in the query: @container card (min-width: 400px). Named containers are self-documenting and immune to DOM reshuffling.

4. Assuming container queries replace media queries

What happens: Developers rip out all media queries, then discover that page-level layout, print styles, and viewport-dependent features (like reducing motion or switching to a single-column app shell) still need them.

Why people make it: The marketing around container queries frames them as “media queries but better.” They are not replacements — they operate on a different axis.

How to avoid it: Use media queries for page-level concerns (viewport width, orientation, prefers-reduced-motion, prefers-color-scheme) and container queries for component-level responsiveness. They compose; they do not compete.

5. Ignoring the fallback story for older browsers

What happens: A component that looks perfect in Chrome collapses into a single stacked column for users on browsers without container query support, or worse, renders with broken spacing.

Why people make it: Baseline support for container queries is now widespread, so teams assume it is universal. It is not — enterprise environments, older Safari versions, and some embedded webviews still lack support.

How to avoid it: Use @supports (container-type: inline-size) to gate enhancements, and write a sensible default layout that works without the query. Progressive enhancement, not progressive breakage.

Best Practices for Production Container Queries

These are the habits that keep container-query codebases maintainable six months after launch, when the original author has moved to another team.

1. Name every container. A named container (container-name: card) makes queries readable and prevents accidental matches when components are reused in unexpected DOM positions. The cost is one extra property; the benefit is bug-free nesting.
2. Keep breakpoints component-local, not global. Define breakpoints where the component actually needs to change shape — a card might shift at 320px, a data table at 640px. Do not reuse a global --bp-md token just because it exists.
3. Prefer inline-size containment. It is cheaper for the browser to compute, does not affect block-axis layout, and covers the overwhelming majority of real responsive needs. Reserve size containment for genuinely two-dimensional components.
4. Document the intent in a comment. A query like @container card (min-width: 400px) tells you what the code does, not why 400px. Add a one-line comment explaining the layout goal so future maintainers do not “clean up” the magic number.
5. Test in a real layout, not in isolation. A component that behaves correctly in a Storybook canvas may break when dropped into a three-column grid or a sidebar. Test container queries where the component actually lives.
6. Combine with @supports for graceful degradation. Ship a baseline layout that works everywhere, then layer container-query enhancements behind a feature check. Users on older browsers get a usable page, not a broken one.

Original Insight: What Changed When We Migrated a 40-Component Design System

Honest framing: I do not have a published benchmark or a controlled study to cite here. What follows is a first-hand account from a design-system migration I worked on in 2025, described at the level of detail I can defend. Treat it as one team’s experience, not a universal result.

Our team maintained a design system of roughly 40 React components used across three product surfaces: a marketing site, a dashboard, and an embedded widget. The dashboard and widget shared components but rendered them at very different widths — the dashboard at 1200px+, the widget at 280–420px depending on where it was embedded. Before container queries, we handled this with a combination of media queries and a prop called compact that flipped internal layout. The prop approach worked, but it meant every consumer of the component had to know which mode to request, and the modes drifted as the design evolved.

We migrated the layout-critical components — Card, Button group, Stat, and Navigation — to container queries over about three weeks. The compact prop was removed entirely. The most useful thing we learned was not about CSS at all: container queries changed the conversation between design and engineering from “which breakpoint does this belong to?” to “what width does this component need to look right?” That second question is answerable by the designer who drew the component, without reference to any page-level layout. It moved a decision that used to require a meeting into a Figma comment.

Two concrete observations from the migration:

• The prop removal was the bigger win. We expected the CSS refactor to be the hard part. It was not. Deleting the compact prop and its TypeScript union type simplified the public API more than any layout improvement did, and it eliminated a whole class of “why is this card in compact mode on the dashboard?” bugs.
• Naming containers was non-negotiable. Our first pass used unnamed containers and we hit the nested-match bug within a week — a Card inside a Stat inside a grid picked up the Stat’s containment context. We renamed every container the following sprint and the bugs stopped. If I were starting over, I would name containers from day one.

The takeaway I would give another team: container queries are worth adopting for the API simplification, not just the layout capability. If your components currently take a “size mode” prop, that prop is a candidate for deletion, and deleting it is the real payoff.

Tools & Resources

Only items I have actually used or verified for this specific workflow.

• MDN Web Docs — CSS container queries. The reference I return to for the exact containment rules and which properties are queryable. Authoritative and kept current with browser behavior.
• Can I use — CSS Container Queries. The fastest way to check current browser support before shipping a query into a client project. Bookmark it; support tables change quarterly.
• Chrome DevTools container query badges. DevTools shows a small badge on elements that are acting as containment contexts, and lets you inspect which container a given query resolved against. This is the single most useful debugging aid for container queries and it is already in your browser.
• CSS @supports at-rule. Not a tool, but the mechanism that makes progressive enhancement practical. Use it to gate container-query enhancements behind a feature check.
• Stylelint. A linter for CSS that can catch undeclared container names and enforce team conventions around container-type. Worth configuring if you have more than two people writing CSS.

Container Query Approach Comparison

The table below compares the three main approaches teams use to make components responsive, based on the tradeoffs we hit during the migration described above.

The practical conclusion from our migration: use media queries and container queries together, and treat size-mode props as technical debt to be retired.

FAQs

What are CSS container queries and how do they differ from media queries?

CSS container queries allow you to style elements based on the size of their parent container, rather than the viewport. Media queries respond to global viewport dimensions, while container queries enable component-level responsiveness. This means a component can adapt to the space it’s placed in, regardless of screen size, making it ideal for reusable design system components.

Which browsers support CSS container queries in 2026?

As of 2026, container queries are supported in all modern browsers: Chrome 105+, Safari 16+, Firefox 110+, and Edge 105+. Global support is over 90%. For older browsers, you can use a polyfill or fall back to media queries. Always check caniuse.com for the latest data.

How do I set up a container query in my CSS?

First, define a containment context on the parent element using `container-type: inline-size;` (or `size` for both dimensions). Then, use `@container (min-width: 400px) { … }` to apply styles when the container is at least 400px wide. You can also name containers with `container-name` for more targeted queries.

Can container queries replace media queries entirely?

No, they serve different purposes. Media queries are still necessary for page-level layout changes (e.g., switching from a single-column to multi-column layout). Container queries are best for component-level adjustments. Use both together for a robust responsive strategy.

What are common mistakes when using container queries?

Common mistakes include: forgetting to set `container-type` on the parent, using `container-type: size` when only inline-size is needed (which can cause layout issues), and overusing container queries for global layout. Also, avoid nesting too many containers, as it can lead to performance overhead and complex debugging.

How do container queries improve performance?

Container queries can improve performance by reducing the number of media queries and enabling more efficient style recalculations. Since styles are scoped to container size changes rather than viewport changes, browsers can optimize rendering. However, excessive use or deep nesting can negate these benefits, so use them judiciously.

Are there any tools to help debug container queries?

Yes, modern browser DevTools (Chrome, Firefox, Edge) now include container query inspection. You can see which container an element belongs to and its current size. Additionally, linters like Stylelint have rules to enforce best practices. For testing, use responsive design mode and resize containers manually.

Conclusion: Why Container Queries Are the Future of Responsive Design

CSS container queries are not just another responsive tool—they represent a fundamental shift in how we build components. Instead of relying on global viewport breakpoints, container queries let components adapt to their own available space. This means a card can look perfect in a narrow sidebar and a wide main column without any extra code. For US development teams building design systems and reusable UI libraries, this is a game-changer. It reduces the need for prop drilling or media query duplication, making components truly self-contained and portable across projects.

As browser support continues to improve (now over 90% globally), the time to adopt container queries is now. Start by auditing your existing components: identify those that currently rely on viewport media queries but would benefit from container-based responsiveness. Then, incrementally refactor them using container-type and @container. You’ll immediately see cleaner code and more predictable layouts. Remember, container queries are not a replacement for media queries—they complement them. Use media queries for page-level layout shifts and container queries for component-level adjustments.

Your next step: Pick one reusable component in your project (like a card or a nav item) and convert its media queries to container queries. Measure the difference in code complexity and visual consistency. To deepen your understanding, explore our guide on CSS Nesting and see how it pairs with container queries to streamline your stylesheets. Ready to master modern CSS? Check out our Advanced CSS Techniques course.