阅读中文版本

CSS Container Queries

Container queries size a component by its parent's dimensions rather than the viewport, enabling truly reusable responsive components.

Definition

A container query is a conditional CSS rule that applies when a designated container element meets a size or style condition, letting a component adapt to the space it occupies.

They matter most for design systems whose components appear in sidebars, cards, and full-width layouts within the same page. Compared to simpler alternatives, this concept fits best when the trade-off it represents is the one the system actually cares about.

When to use it

A common use case is applying it at the boundary where the cost of getting it wrong is highest, and the scenario usually involves a concrete guarantee the system must uphold. Unlike an ad hoc approach, it makes that guarantee explicit, reviewable, and testable.

How it works

A query targets the nearest ancestor declared as a containment context, so authors set container-type on the wrapper whose width should drive the component’s layout.

Size containment means the container’s size cannot depend on the content it queries, and circular dependencies are resolved by ignoring self-referential conditions.

Trade-offs and alternatives

Style container queries extend the idea to custom property values, allowing a component to respond to a theme token set by an ancestor rather than to raw dimensions. The main drawback is the extra complexity it introduces, so the benefit should clearly outweigh that cost before a team adopts it.

Common misconceptions

A persistent misconception is that container queries measure the viewport like media queries. Another is that an element becomes a query container automatically. For example, an engineer who assumes otherwise may design around a guarantee that does not actually exist, which only becomes obvious under load or failure.

Anti-patterns to avoid

Two recurring anti-patterns are to creating many nested size containers without need and to querying a container for changes that originate on the queried element itself. Both tend to surface as hard-to-debug production issues rather than obvious test failures. Related concepts include Third-Party Cookies and Storage Partitioning, Subresource Integrity (SRI), Preconnect and DNS-Prefetch Hints.