Container Queries 2026 — A Field Guide

Media queries respond to the viewport. Container queries respond to the element's own container — which is what component authors actually wanted the whole time. A card component that needs to switch from a stacked to a side-by-side layout doesn't care how wide the browser window is; it cares how much space its parent container has given it. Container queries shipped in all major browsers in 2023 and by 2026 are safe to use without a fallback in the vast majority of production codebases.

The basic syntax

You opt an element into being a query container with container-type, then query against it from a descendant using @container. The container needs a name only if you have nested containers and need to target a specific ancestor; otherwise the nearest containing ancestor is used implicitly.

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

.card {
  display: grid;
  grid-template-columns: 1fr;
  gap: 0.75rem;
}

@container card (min-width: 400px) {
  .card {
    grid-template-columns: 120px 1fr;
    align-items: start;
  }
}

inline-size vs size containment

container-type: inline-size is what you reach for almost every time — it queries against the container's width (inline dimension in a horizontal writing mode) and applies layout, style, and inline-size containment. container-type: size queries both dimensions but requires the container to have an explicit height, since containment means the element can't size itself based on its children — that's usually more restrictive than component authors want. Stick to inline-size unless you specifically need to query height.

Container query units

Alongside the @container at-rule, CSS added container query length units — cqw, cqh, cqi, cqb, cqmin, cqmax — which scale relative to the query container the same way vw/vh scale relative to the viewport. A heading using font-size: clamp(1rem, 4cqi, 2rem) scales fluidly with its container's inline size rather than the viewport, which is genuinely useful for components that get dropped into sidebars, modals, and full-width sections with very different available widths.

Style queries (newer, less universal support)

Style queries let you query a container's custom property values rather than its dimensions — @container style(--theme: dark), for example — so a component can adapt based on a design-token value set higher in the tree instead of a size. Support landed later than size queries and is less consistently available across engines as of 2026, so treat style queries as progressive enhancement rather than something to depend on for critical layout.

Practical migration from media-query-heavy components

The components that benefit most from converting to container queries are the ones currently duplicated for different placements — a "card" that has a slightly different version for the sidebar versus the main feed because the media-query breakpoints didn't line up with actual available space. Converting those to one component driven by container queries usually removes real duplication, not just theoretical duplication.

Wrapping up

Container queries are one of the rare CSS features that directly reduce component duplication rather than just adding a new visual capability. If you have components hand-duplicated for different contexts because a media-query breakpoint never quite matched the actual space available, that's the concrete signal it's time to switch to container-type and @container instead.