CSS Container Queries Explained: When to Use Them Now

The hardest responsive design bug of the last decade was never about screen size. It was that a card component had no way to know how wide its own parent was, only how wide the browser window was. CSS container queries fix that, and the feature just quietly leveled up again in 2026, which makes this the right moment to learn it properly instead of skimming a tutorial from 2023.

Media Queries Answer the Wrong Question for a Reusable Component

A media query only ever asks one thing: how wide is the viewport right now. That question works fine for a full page layout, but it falls apart the moment you build a card, a widget, or any component meant to be dropped into a sidebar on one page and a three column grid on another. The viewport might be 1400 pixels wide in both cases, yet the component itself has 320 pixels of room in one spot and 900 in the other. A media query cannot see that difference, because it was never designed to look at anything smaller than the whole window.

CSS container queries solve exactly that problem. Instead of asking about the viewport, a container query asks how much space the component's own container has, and applies styles based on that answer. The component becomes self-aware of its placement, which matters once the same card, table row, or nav item gets reused across a dozen layouts in one component-driven codebase.

Container-Type and Container-Name Are the Two Switches You Flip

To query a container's size, that container first needs a containment context, created with the container-type property. Per MDN's CSS containment documentation, there are three relevant values: size applies layout, style, and size containment and lets you query both width and height; inline-size applies layout, style, and inline-size containment and only lets you query the inline dimension (width, in a standard horizontal writing mode); and normal, the default, is not a size query container at all, though it can still be one for name-only or style queries.

A typical setup looks like this:

• .card-wrapper { container-type: inline-size; container-name: card; }
• @container card (width > 480px) { .card-title { font-size: 1.5rem; } }

container-name is optional. Without it, a query simply targets the nearest ancestor that has a containment context. With it, you can have several nested containers and point a query at a specific one by name, which matters once a design system nests cards inside panels inside grids. MDN also documents name-only queries, which check whether an element has an ancestor with a given container name and skip the size condition entirely, useful for scoping a style to "inside this named region" without caring about width at all.

Every Browser Shipped Size Queries on Its Own Timeline

Coverage of new CSS features often says a feature arrived "in 2023" as if every browser shipped it the same week. It did not. Chrome and Edge 105 added size-based container queries and the related container query units first, which Chrome's own developer blog dates to its container query polyfill post published September 15, 2022. Safari 16 shipped the same feature in its own release that followed. Firefox was last, landing support in Firefox 110, released February 14, 2023, which is the date MDN's Firefox 110 developer release notes and web.dev's February 2023 platform roundup both point to as the moment all three engines were finally aligned.

That gap between Chrome's September 2022 shipping date and Firefox's February 2023 date is the entire reason Baseline exists as a concept: a feature only becomes safe to use without a fallback once the slowest of the core browsers catches up, not once the fastest one ships it. Browsers now ship new versions roughly every two weeks, which shortens the wait between a feature landing in one engine and catching up in the others, but it does not erase it.

Style Queries Just Reached Baseline, and They Matter More Than Size

Size queries check a number. Style queries check a declaration, using the style() function inside @container to test whether a container has a given CSS custom property set to a given value, for example @container style(--theme: dark) { ... }. That lets a component change based on a design token its container sets, rather than on pixels, which is a far more common need in a real design system than raw width thresholds. According to web.dev's Baseline monthly digest for May 2026, style queries only just crossed into Baseline newly available status that month, meaning this half of the specification is roughly three years younger in practice than the size-query half most tutorials still treat as the whole feature.

Newly available is not the same as safe for every audience. Under the Baseline project's own definition, a feature only earns the stronger "widely available" badge 30 months after it first becomes newly available, a threshold web.dev's definition update post ties to adoption data showing most features reach roughly 95 percent of global users within that window. Style queries will not clear that bar until roughly late 2028. Teams building anything a general audience depends on today should treat style queries as promising but still worth a feature check, not as something to ship without a fallback the way size queries now can be.

Use Container Queries When a Component Travels, Not When Only the Page Does

The decision rule is simpler than most explainers make it sound. Reach for container queries when a single component gets reused across genuinely different widths: a card that lives in a three-column grid on the homepage and a single narrow sidebar slot on an article page, a product tile that appears in both a dense catalog and a "related items" rail, or any shared component library consumed by multiple products. Skip container queries, and stick with plain media queries, when your breakpoints already map cleanly to the viewport: a single-column blog layout, a marketing landing page with one responsive structure, or any page where "the component's width" and "the window's width" are effectively the same number.

• Use container queries if: you maintain a design system or component library consumed in more than one layout context, and you are already shipping to current browser versions.
• Skip container queries if: your layout is a single responsive page shell, or your audience includes a meaningful share of browsers more than three years old, where size queries alone (not just style queries) may still be missing.
• Use style queries cautiously if: the audience is internal tooling or a modern-browser-only product; wait or add a fallback for anything public facing until the feature is further past its May 2026 Baseline milestone.

This is primarily a decision for frontend engineers and designers maintaining shared component libraries, not for anyone building a single static page, where a couple of ordinary media queries still do the job.

The Catch Nobody Mentions: Containment Can Collapse Your Layout

Most introductions to container queries skip the actual cost of turning an element into a query container. Setting container-type: size does not just enable a query, it applies real CSS size containment, and per MDN's own containment documentation, size containment tells the browser to lay the element out as though it has no content at all unless it can otherwise determine a size. In practice that means a container sized only by its children can collapse to zero height the moment you add container-type: size, because the browser no longer looks inside to measure it.

The fix, documented on MDN's contain-intrinsic-size and contain-intrinsic-height pages, is to explicitly tell the browser what size to assume with a property like contain-intrinsic-height: 400px, or to use container-type: inline-size instead, which only contains the inline dimension and leaves height to behave normally. This is the steelman case for the critics who say container queries add engineering overhead that viewport media queries never carried: a media query cannot accidentally zero out your layout, and a container query implemented carelessly can. The honest fix is not "avoid container queries," it is "default to inline-size unless you specifically need to query height, and budget time to set intrinsic sizes when you do."

Common Questions About CSS Container Queries

Do container queries replace media queries entirely? No. Media queries still own page-level, viewport-based decisions such as switching a whole layout to one column on a phone. Container queries handle component-level decisions inside that layout. Most real projects use both together, not one instead of the other.

Do I need a polyfill to use container queries today? For size queries, no. They have been Baseline widely available since February 2023, per MDN, so current and recent versions of every core browser support them without a fallback. For style queries, which only reached Baseline newly available in May 2026, a feature check or graceful fallback is still the safer default for public facing sites.

What is the difference between container query units and viewport units? Viewport units like vw scale to the browser window. Container query units like cqw and cqi, documented on MDN's container queries guide, scale to the nearest query container instead, which is what lets a component's font size grow or shrink with its own box rather than the screen.

Sources

• MDN: CSS container queries
• MDN: @container
• MDN: contain-intrinsic-size
• Chrome Developers: Container queries begin to land in stable browsers
• MDN: Firefox 110 release notes
• web.dev: New to the web platform in February 2023
• web.dev: May 2026 Baseline monthly digest
• web.dev: A definition update for Baseline