Container Queries

Specialized CSS length units that resolve relative to a query container's dimensions rather than the viewport. These units enable precise, context-aware sizing within components.

• cqw: 1% of the query container's width
• cqh: 1% of the query container's height
• cqi: 1% of the inline size (writing-mode aware)
• cqb: 1% of the block size (writing-mode aware)
• cqmin / cqmax: The smaller or larger of cqi and cqb

Use these units inside @container query blocks to create truly proportional component internals that scale with their parent, not the viewport.

The container-type CSS property establishes an element as a containment context for size queries. Without it, descendant elements cannot query the container's dimensions.

• size: Establishes containment for both inline and block dimensions. Queries can use width and height.
• inline-size: Establishes containment only for the inline axis. Most common for responsive components.
• normal: The element is not a query container (default).

Combine with container-name to create named containers that can be targeted by specific @container rules, enabling nested query contexts.

The @container CSS at-rule defines a conditional block of styles that apply when a query container meets specified size conditions. It is the syntactic counterpart to @media queries.

Syntax:

cssCopy
@container (min-width: 400px) {
  .card { grid-template-columns: 1fr 1fr; }
}

Named containers:

cssCopy
@container sidebar (max-width: 300px) {
  .widget { flex-direction: column; }
}

Supports range syntax using comparison operators (>, <, >=, <=) and logical combinators (and, or, not).

An extension of container queries that allows components to respond to the computed style values of a parent container, not just its size. This enables context-aware theming and layout adaptation.

Example:

cssCopy
@container style(--theme: dark) {
  .child { color: white; background: #1a1a1a; }
}

• Query custom properties defined on the container
• Detect parent display modes (grid vs. flex)
• Adapt to inherited typography or color scheme changes

Browser support is currently limited compared to size-based container queries. Progressive enhancement is recommended.

Applying container-type implicitly sets contain: layout style on the element, which has critical side effects for component architecture.

Key implications:

• The container becomes a containing block for absolutely positioned descendants
• Margin collapsing is prevented at the container's boundaries
• The container cannot rely on content to determine its own intrinsic size (size containment)
• Float clearance is contained within the element

These constraints ensure the container's size is deterministic and independent of its descendants, preventing circular layout calculations. Always test existing components for layout shifts when adding container-type.

Understanding when to use each query type is essential for modern responsive architecture.

Media Queries respond to the viewport:

• Page-level layout decisions (header, footer, global navigation)
• Device characteristics (prefers-reduced-motion, color-scheme)
• Top-level breakpoints

Container Queries respond to the parent container:

• Reusable component internals (cards, widgets, sidebars)
• Context-dependent styling when the same component appears in multiple layouts
• Design system primitives that must work in any slot

Best practice: Use media queries for page scaffolding and container queries for component internals. They are complementary, not competing, tools.