Container Queries

Introduction

Container queries (@container) apply styles based on a parent container's size — not the viewport. Staff engineers use them when components live in sidebar, main, and modal contexts where viewport media queries pick wrong layout. Define container-type: inline-size (or size) on ancestor, query with @container (min-width: …).

Container queries complete responsive component design — the component is responsive to its context, not the window.

Business problem

Business pressure: Product card looks correct full-width on mobile but broken in 240px dashboard widget — viewport is desktop-wide. Container queries fix component-local responsive without prop-drilling breakpoint classes from parent.

• DS quality: One card component, all contexts.
• Micro-frontends: Unknown parent width in federated shell.
• Editor: CMS columns of varying width.

Why this feature exists

Platform history: Element queries dreamed for years; container queries shipped Chromium 105+, Safari 16+, Firefox 110+ (2023).

• Problem solved: Viewport queries for component internals.
• Modern role: container-type + @container + container query units cqw.

Browser rendering perspective

Rendering impact: Container size changes trigger contained subtree style recalc — smaller blast radius than viewport resize if containment set. container-type creates size containment — may affect layout in subtle ways — test overflow.

• Containment: size containment clips overflow — document padding on container.

Internal browser workflow

Setup: ancestor container-type → child @container rules → optional container-name for named queries.

Feature deep dive

Product card example:

.card-container { container-type: inline-size; container-name: card; }
.card { display: flex; flex-direction: column; gap: 0.5rem; }
@container card (min-width: 28rem) {
  .card { flex-direction: row; align-items: center; }
  .card__media { width: 40%; }
}
@container (min-width: 20rem) {
  .card__title { font-size: 1.25rem; }
}

Syntax

container-type: inline-size (width only), size (width+height — strict containment). Units: cqw, cqh, cqi container query units.

Examples

Named container chain:

.sidebar { container-type: inline-size; container-name: sidebar; }
@container sidebar (max-width: 15rem) {
  .nav { flex-direction: column; }
}

Real-world use

Shopify Polaris exploring container queries for admin cards. Design system articles 2023–2024 adopt @container for card, table, and nav patterns. WordPress block themes use container queries in block layouts.

Real production example

Pattern: DS components document required container-type on parent wrapper in Storybook.

Enterprise use case

Enterprise: Dashboard widgets standardize on container queries — grid cell width varies.

Accessibility considerations

A11y: Layout change at container width must not trap focus — modal card layout switch still keyboard accessible.

Performance considerations

Performance: Many nested containers — profile resize; avoid deep container-type on every wrapper.

SEO considerations

SEO: Content in narrow containers still indexed — ensure not display:none at default container size.

Scalability considerations

Scale: Fallback @media for browsers without @container — @supports (container-type: inline-size).

Common production issues

Failures: Forgot container-type — queries never fire. size containment clips dropdown menus.

Debugging guide

Debug: Chrome DevTools → container badge on elements; inspect container size vs query.

Best practices

• container-type on direct layout parent of responsive component.
• Storybook stories in multiple container widths.
• @supports fallback for legacy browsers.

Anti-patterns

• container-type: size everywhere — overflow bugs.
• Duplicate viewport @media and @container for same rule without reason.

Trade-offs

• Container queries: contextual components.
• Viewport queries: page-level layout still appropriate.

Architecture review questions

• DS components document container requirements?
• Fallback strategy for @container?

Interview questions

Hands-on exercise

Exercise: Card with @container layout switch; Storybook at 200px and 400px container widths.

Staff engineer notes

• Container queries shift responsive testing to component stories — not only viewport presets.

Common pitfalls

• size containment breaking position:absolute popovers.

Try it yourself

Edit the CSS panel — the preview updates live. Use DevTools Performance and Accessibility panels to validate.

Summary

Container queries enable components to adapt to parent container dimensions — essential for dashboards, CMS columns, and design system components in variable contexts.

Key takeaways

• @container responds to parent size, not viewport.
• container-type on ancestor required.