Container Queries

Why Container Queries

Media queries respond to viewport width, but components do not know their context. A card component might be 300px wide in a sidebar or 800px wide in a main column — the same viewport, different needs.

Container queries solve this by letting components adapt to their parent size. This is the biggest shift in responsive CSS since media queries themselves.

• Components become truly portable — same markup, any layout context
• Eliminates breakpoint prop drilling in React and other frameworks
• Supported in all modern browsers since 2023

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

Setting Up Containers

Apply container-type: inline-size to the element whose width should trigger queries. Use container-name for named containers when nesting queries. The container-type: size keyword queries both width and height but requires explicit dimensions.

Only direct children and descendants can use @container rules against that container. Plan your HTML structure so the container wrapper is one level above the styled component.

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

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

Writing @container Rules

Container query syntax mirrors media queries: @container (min-width: 400px) { }. Styles inside apply when the container meets the condition. Named containers are targeted with @container product (min-width: 300px).

Combine container queries with existing media queries — media queries for page layout, container queries for component internals.

@container (min-width: 400px) {
  .card {
    display: grid;
    grid-template-columns: 120px 1fr;
    gap: 1rem;
  }
  .card__image { aspect-ratio: 1; }
}

@container product (min-width: 250px) {
  .product-card { flex-direction: row; }
}

Container Query Units

Container query length units are relative to the container, not the viewport. cqw is 1% of container width, cqh is 1% of container height, cqi and cqb are inline and block sizes.

Use cqw for fluid padding and font sizes within components. A font-size: clamp(0.875rem, 2cqw + 0.5rem, 1.125rem) scales with the component, not the page.

• cqw units require a defined container-type on an ancestor
• Use cqi for inline-size-aware spacing in horizontal writing modes
• Container units enable self-contained responsive components in design systems

.widget-title {
  font-size: clamp(1rem, 3cqw + 0.5rem, 1.5rem);
  padding: 2cqi;
}

Practical Patterns

Container queries shine in design systems. A data table component can switch from stacked cards to a full table based on its wrapper width. Navigation components collapse to icons in narrow containers.

Test components in isolation at various container widths using Storybook or component playgrounds. This catches responsive bugs that viewport-only testing misses.

@container (max-width: 320px) {
  .data-table { display: none; }
  .data-cards { display: block; }
}

@container (min-width: 321px) {
  .data-table { display: table; }
  .data-cards { display: none; }
}