Media queries revolutionised responsive web design by letting styles adapt to viewport dimensions. But they always had a fundamental limitation—components couldn’t respond to their container size, only to the entire viewport. A sidebar widget couldn’t know whether it occupied 200px or 600px of width; it only knew the browser window was 1920px wide.

Container queries solve this by letting elements query their parent container’s size rather than the viewport. After years as a CSS working draft and experimental feature, browser support finally reached production viability in late 2024. As of March 2026, container queries work reliably across modern browsers and are changing how developers approach responsive component design.

The Fundamental Syntax

Container queries require two pieces: declaring a containment context and querying that context. You mark an element as a container using the container-type property, then child elements can query that container’s dimensions.

.card-container {
  container-type: inline-size;
  /* or: container-type: size; */
}

.card-content {
  padding: 1rem;
}

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

The inline-size value creates containment on the inline axis (horizontal in left-to-right languages) while allowing normal sizing on the block axis. The size value establishes containment on both axes, which is more restrictive but enables querying height as well.

Container units complement the queries. Units like cqw (container query width), cqh (container query height), and cqi (container query inline) let you size elements relative to their container rather than the viewport. A heading can be font-size: 5cqw to scale with container width regardless of viewport size.

Where Container Queries Actually Help

The most obvious use case involves reusable components that appear in different contexts. Consider a product card that might display in a 4-column grid, a sidebar, or full-width on mobile. With media queries, you’d write breakpoints based on viewport width and hope the card occupies expected widths at those breakpoints.

Container queries let the card adapt to its actual width. In a wide grid column, it displays image beside content. In a narrow sidebar, it stacks vertically. In a medium container, perhaps image above and content in two columns. The component encapsulates its responsive logic instead of coupling to viewport dimensions.

Navigation patterns benefit similarly. A navigation component might be full-width in page headers, sidebar width in app layouts, or modal-overlay width in mobile menus. Container queries let one component implementation adapt to each context without external breakpoint management.

Dashboard widgets, form fields, data visualisations, media players, and countless other components have inherent responsive requirements based on available space rather than viewport size. Container queries make that space-based responsiveness explicit and maintainable.

Performance Considerations

Container queries introduce new browser layout calculations. When container dimensions change, the browser must re-evaluate container queries, potentially triggering style recalculation and layout for contained elements. This happens in addition to normal reflow calculations.

Early implementations had performance issues with deeply nested container query contexts or rapidly changing container sizes. Modern browser optimisations largely addressed these problems, but pathological cases can still create lag.

Avoid container queries on elements that resize frequently or have many descendant elements querying containment. Animation-driven size changes trigger constant query re-evaluation. Components with hundreds of children that each use container queries can create calculation bottlenecks.

The Mozilla Developer Network documentation recommends limiting container query depth—avoid nesting container query contexts more than three or four levels deep when possible. This keeps calculation complexity manageable.

Named Containers

When multiple parent elements could serve as containers, named containers disambiguate which to query:

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

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

@container sidebar (min-width: 300px) {
  .widget {
    /* styles for widgets in sidebars */
  }
}

@container main (min-width: 600px) {
  .widget {
    /* styles for widgets in main content */
  }
}

This lets the same component query different ancestor containers and apply appropriate styles. A widget can respond to both its sidebar container and its section container simultaneously, applying whichever query matches first in cascade order.

The Flexbox and Grid Relationship

Container queries combine powerfully with flexbox and grid layouts that inherently create variable-width containers. A grid with fr units creates columns that resize with viewport, and contained elements respond to those container widths rather than viewport width.

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

.grid-item {
  container-type: inline-size;
}

@container (min-width: 300px) {
  .grid-item-content {
    /* applied when grid item reaches 300px */
  }
}

This creates truly responsive grids where components adapt to their actual space allocation rather than estimated breakpoints. The grid calculates column widths, components respond to those widths. No coordination required.

Browser Support Reality Check

According to Can I Use, container queries have 90%+ global browser support as of early 2026. Safari 16+, Chrome 105+, Firefox 110+, and Edge 105+ all implement the feature. The main gap is older mobile browsers and legacy desktop installations.

Progressive enhancement handles the gap reasonably. Browsers without container query support ignore @container rules and apply base styles. You provide sensible defaults that work without queries, then enhance with container queries where supported.

Polyfills exist but add JavaScript dependencies and performance overhead that often exceeds the value they provide. Most production use cases are better served by progressive enhancement unless container queries are absolutely critical to the experience.

Containment Side Effects

Setting container-type creates CSS containment with side effects beyond query enablement. Size containment prevents element size from depending on descendants’ size, which can break layouts expecting natural content sizing.

Layout containment creates new formatting contexts and stacking contexts, affecting positioned descendants and z-index behaviour. This occasionally produces unexpected rendering where absolutely positioned children no longer position relative to expected ancestors.

Testing container implementations thoroughly matters. What works in one browser might render differently in another due to subtle containment interpretation differences. Chrome, Safari, and Firefox occasionally disagree on edge cases involving overflow, positioning, or stacking contexts.

Where Container Queries Don’t Help

Container queries don’t replace media queries—they complement them. Page-level layout decisions based on viewport size, orientation, or display capabilities still require media queries. Device-specific features like hover support or high-DPI displays aren’t container concerns.

Accessibility features that depend on user preferences—reduced motion, contrast preferences, colour schemes—use media queries targeting user settings rather than container dimensions. Container queries address component size adaptation, not user preference adaptation.

Practical Adoption Strategy

Start using container queries for new component development where it makes sense. Cards, widgets, navigation, media components, forms, and data displays are good candidates. Don’t retrofit container queries into working code unless you’re already refactoring.

Establish container query conventions on projects—naming schemes for container contexts, preferred breakpoints, whether to use inline-size or size containment. Consistency makes container queries maintainable across teams.

Document which components use container queries and their expected container size ranges. Unlike media queries where viewport breakpoints are project-wide knowledge, container query breakpoints are component-specific and harder to discover from inspecting code.

Container queries represent a fundamental improvement in CSS responsive design capability. They’re not revolutionary—good developers built functional responsive components with media queries for years. But they make component-based responsive design dramatically more elegant and maintainable. After years of waiting, they’re finally ready for widespread production use.