Container Queries

Components should respond to available space — not only the viewport breakpoint.

01 — Purpose

Respond to container space

Container queries let components adapt to available space — not only the viewport breakpoint.

Viewport media queries assume the whole screen changed. Cards in a sidebar, split layout, or dense dashboard need to respond to their column — container queries make that possible without prop-drilling breakpoints from the page.

Complements responsive patterns in the CSS standard and layout work in CSS architecture.

02 — Principles

Components adapt to context

Responsive behaviour belongs on the component where the constraint lives.

  • define containment on a wrapper — container-type or shorthand container
  • name containers when multiple query contexts nest
  • viewport queries for page-level layout; container queries for component innards

03 — Practice

Good container query use

Reusable components, modular layouts.

  • card grids that switch from stacked to horizontal based on card width — not page width
  • navigation that collapses when the header column is narrow
  • data tables or stats that reflow inside dashboards and side panels
  • pair with flex/grid — container queries decide internal arrangement 
.content-card-grid {
  container-type: inline-size;
}

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

04 — Avoid

Container query pitfalls

Viewport-only thinking and breakpoint sprawl do not disappear — they shift.

  • duplicating every viewport breakpoint at container size — pick meaningful thresholds
  • forgetting containment — queries silently fail without a defined container
  • layout assumptions that break when the same component lives in main and sidebar

05 — Close

Component-level resilience

If a component only works full-width on a desktop page, it is not reusable yet.

Test components in narrow columns, modals, and split views — not only at 375px and 1440px viewport. Container queries catch layout bugs viewport queries miss.

Related: cascade layers, tables pattern for responsive data.