CSS Container Query

CSS Container Queries: responsive components, not pages

Media queries have driven responsive design since 1995, but they only react to the viewport. That means a card placed in a sidebar and the same card placed in the main area both inherit breakpoints designed for the whole window — even if the sidebar is 280px wide and the main area is 960px wide. Container queries fix that mismatch: they let a component react to its parent container rather than the screen. A single .card component can switch from a stacked mobile layout to a horizontal grid the moment its parent crosses 400px — no matter where on the page that parent lives.

Browser support arrived in late 2022 and early 2023: Chrome 105+, Safari 16+, Firefox 110+. That covers more than 92% of global traffic in 2026, so most production codebases can adopt container queries without polyfills. For legacy browsers, the container-query-polyfill exists but is heavy; progressive enhancement is the recommended fallback strategy.

Syntax in two parts

First, declare a containment context on the parent. Then write the query against that context:

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

@container card (min-width: 400px) {
  .card {
    display: grid;
    grid-template-columns: 1fr 2fr;
  }
}

container-type accepts three values: inline-size (only the inline axis — usually width — is queryable; the most common choice), size (both axes — heavier because it forces layout containment), and normal (the default — no containment). @container uses the same condition syntax as @media but is scoped to the nearest container ancestor that matches its name.

Container query units

Alongside the at-rule, CSS introduced container-relative length units: cqw (1% of container width), cqh (height), cqi (inline), cqb (block), cqmin, and cqmax. They work like vw/vh but are scoped to the container instead of the viewport — perfect for fluid typography inside a card that should not depend on the window size.

Where they shine

• Card components that swap between stacked and side-by-side layouts;
• Navigation patterns that turn into hamburger menus by sidebar width;
• Sidebar widgets reused inside dashboards and modals;
• Multi-column blog post cards in CMS-driven grids;
• Design-system primitives shipped without knowing the consumer's layout.

FAQ

Do container queries replace media queries? No — they complement them. Keep @media for top-level page layout (one column vs two, navigation drawer vs bar) and use @container for component variants that should adapt regardless of where they are dropped.

When should I pick @container over @media? A useful heuristic: media = page, container = component. If the rule depends on the device or the whole window, it is a media query. If it depends on the slot the component occupies, it is a container query.

What about Tailwind users? Tailwind 3.2+ ships the @container plugin, letting you write @container <div class="@md:flex"> directly. Styled Components, Emotion and most CSS-in-JS libraries also expose container query helpers.

Is there a performance cost? Containment is optimized: the browser only re-evaluates rules when the container's relevant dimension changes. Avoid container-type: size unless you need both axes — it forces full layout containment, which is more expensive than inline-size.