CSS Container Queries Explained: What They Are and When to Use Them

CSS Container Queries let an element's styles change based on the size of its containing element, rather than the size of the entire browser viewport — the same basic idea as a traditional media query, but scoped to a component's actual available space instead of the whole page. This closes a genuinely long-standing gap in CSS for building components meant to be reused in different layout contexts.

The problem container queries actually solve

A traditional media query answers "how wide is the browser window?" — which works fine for page-level layout decisions (switching from a three-column to a single-column page layout on a narrow screen), but breaks down for a genuinely reusable component. A card component might need to render differently depending on whether it's placed in a wide, main content area or squeezed into a narrow sidebar — but the viewport width is identical in both cases, since it's the same page. A media query has no way to express "style this differently based on how much space *this specific component* actually has," only "style this differently based on the browser window's total width." Before container queries, developers worked around this with JavaScript-based solutions (measuring an element's width and toggling classes) or by avoiding genuinely responsive, context-aware components altogether.

Basic syntax

Using a container query requires two things: first, marking an element as a containment context using the `container-type` property, and second, writing a `@container` rule that targets descendants of that container based on its size.

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

@container card (min-width: 400px) {
  .card-title {
    font-size: 1.5rem;
  }
  .card {
    display: flex;
    flex-direction: row;
  }
}

In this example, `.card-title` and `.card` only get the wider-layout styles when their containing `.card-wrapper` is at least 400px wide — regardless of how wide the overall page or viewport is. Drop the exact same `.card` component into a narrow sidebar, and it automatically renders in its narrower, stacked form; drop it into a wide main content area, and it automatically renders in its wider, side-by-side form — with zero JavaScript and no need for the component itself to know or care where it's been placed.

`container-type` values

• `inline-size` — the most commonly used value; queries respond to the container's width (in a standard horizontal writing mode), which covers the vast majority of real responsive-component use cases.
• `size` — queries can respond to both width and height, useful for components where vertical space genuinely matters to the layout decision, though it comes with more layout-containment side effects to be aware of.
• `normal` — the default (no containment), meaning the element doesn't act as a query container at all.

Container query units: a related, useful addition

Alongside `@container` rules, CSS also introduced container-relative units — `cqw`, `cqh`, `cqi`, `cqb` (container query width/height/inline/block) — which let you size an element as a percentage of its *container's* dimensions, the same conceptual relationship `vw`/`vh` have to the viewport. This is useful for fluid typography or spacing that should scale with a component's own container rather than the page's overall viewport, giving genuinely container-relative fluid sizing without needing a `@container` rule at all for the simpler cases.

How this compares to CSS Grid and Flexbox

It's worth being clear that container queries don't replace Grid or Flexbox — they solve a different problem entirely. Grid and Flexbox control how elements are *arranged* within a layout; container queries control *which styles apply* based on available space. In practice, they're commonly used together: Flexbox or Grid handles the actual arrangement of a component's internal elements, while a container query decides which arrangement (and which specific style values) should apply in the first place, based on the space actually available to that component in its current context.

Browser support and practical adoption

Container queries reached broad support across all major modern browsers (Chrome, Firefox, Safari, Edge) starting in 2023, which by now makes them safely usable for most production projects without a fallback needed for typical modern-browser audiences — though, as with any relatively recent CSS feature, checking current browser support against your specific project's actual audience requirements (particularly if you need to support notably older browser versions) remains good practice before relying on them for a critical layout decision.

Naming containers for clarity in nested layouts

The `container-name` property (used alongside `container-type` in the earlier example) matters more than it might first appear, especially in a page with multiple nested containers. Without a name, a `@container` rule queries the *nearest* ancestor with containment applied — which can produce confusing results if a component is nested inside more than one container context (a card inside a sidebar, which is itself inside a page-level container). Naming containers explicitly (`container-name: card`) and referencing that name in the `@container` rule (`@container card (min-width: 400px)`) removes the ambiguity, making clear exactly which ancestor's size a given rule is actually responding to, rather than relying on whichever container happens to be nearest in the DOM tree.

Combining container queries with logical, range, and compound conditions

`@container` rules support the same range syntax and logical combinators as modern media queries — `@container (400px <= width <= 800px)` for a bounded range, or combining conditions with `and`/`or` (`@container (min-width: 400px) and (min-height: 300px)`) for more precise, compound layout decisions. This means a component can define several distinct breakpoints of its own — a compact mode below a certain width, a comfortable mode in a middle range, and a fully expanded mode above a larger width — all scoped entirely to that component's own container, independent of whatever breakpoints the page itself uses for its own, separate viewport-level media queries.

Style queries: a newer, related capability

Beyond size-based container queries, CSS is also gaining container style queries, which let a component's styles respond to a custom CSS property's value on its container, rather than the container's dimensions — for instance, styling a component differently depending on whether its container has a `--theme: dark` custom property set, without needing a separate class name or a JavaScript-driven attribute toggle to communicate that context down to the component. Style queries have less mature, later browser support than size-based container queries as of this writing, but represent the same underlying idea taken further: letting components respond to genuine contextual information from their surroundings, not just their raw pixel dimensions.

A subtlety: the containment side effects of container-type

Setting `container-type: inline-size` (or `size`) on an element doesn't just enable container queries on its descendants — it also applies CSS containment, which affects how the browser calculates that element's own layout, style, and (for `size`) paint boundaries. In practice, this mostly matters for edge cases: an element with `container-type: size` set, for instance, needs an explicit height specified (via CSS, not just letting its content determine height), since strict size containment removes the ability for its own size to be determined by its children's content. This is a genuine, if narrow, gotcha worth testing for when a container query rule seems to apply correctly, but the component's own layout still looks subtly different than expected — checking whether it's specifically a containment side effect, rather than a query-logic bug, is worth doing early rather than debugging the query syntax repeatedly for a problem that isn't actually there.

Progressive enhancement: a safe way to adopt container queries today

Given the strong but not universal browser support, a common, low-risk adoption pattern is to define a component's baseline, simplest styles outside any `@container` rule (so every browser, including any that don't support container queries, gets a reasonable, working layout), then layer the container-query-specific enhancements on top for browsers that do support the feature. This means an unsupported browser simply doesn't get the enhanced, context-aware behavior and falls back to the sensible baseline, rather than breaking or rendering incorrectly — a graceful degradation path that makes adopting container queries low-risk even before support is universal across every browser a project might need to consider.

A realistic use case: a component library

The clearest, most common real-world case for container queries is a shared component library used across many different pages and layout contexts within the same product — a notification card, a product tile, a profile summary widget — each of which might legitimately need to render differently depending on whether it's shown in a wide dashboard panel, a narrow sidebar, or a compact list view. Before container queries, achieving this properly responsive, context-aware behavior required either JavaScript measurement hacks or maintaining separate style variants manually applied based on where a component happened to be placed. Container queries let the component genuinely own its own responsive behavior, adapting automatically to wherever it's dropped, which is a meaningfully cleaner architecture for any team maintaining a real, reused component system.

The short version: container queries let a component respond to the size of its own container rather than the overall viewport, solving the specific, long-standing problem of building genuinely reusable, context-aware components that media queries alone couldn't address. They complement rather than replace Grid and Flexbox, work well alongside container-relative units for fluid sizing, and are now broadly supported enough in modern browsers to use confidently in most production projects.