Container Queries and Container Units

Intermediate

Container Queries let a component respond to the size or other queryable state of an appropriate ancestor container instead of asking only about the viewport. This lesson owns the container-query model: establishing query containers, selecting a query container, evaluating @container conditions, and using container-relative length units.

The central distinction is the source of the condition. Media Queries evaluate the user agent or output environment; Container Queries evaluate a query container associated with the element being styled. The two mechanisms can be used together, but they answer different questions.

Container conditions are local

A viewport breakpoint describes the available outer environment. A container query describes whether a component has enough space in its own containing context. The component can therefore react differently when two instances occupy different amounts of space on the same page.

?

Establishing a query container

An element becomes a query container for size queries when its container-type establishes the relevant containment. The commonly useful value is inline-size: it makes the container’s inline axis queryable without turning every dimension into a container-query dependency.

?

Choosing container-type

container-type controls what kind of containment is established for container-query purposes. Treat it as part of the component boundary: choose the narrowest queryable dimension that answers the component’s actual question rather than adding containment everywhere.

?

Naming containers

container-name associates one or more names with a query container. A named @container condition can skip a nearer eligible container and evaluate against the named ancestor instead. Names are useful when nested components have different query responsibilities.

?

How container selection works

For an unnamed @container query, evaluation starts with the nearest ancestor that is an eligible query container for the queried feature. For a named query, the search is constrained by the requested container name. This selection step happens before the condition itself is evaluated.

?

Writing container conditions

The condition inside @container uses the same general conditional-query style you learned with media queries: a feature can be compared to a value, and conditions can be combined. The difference is the object whose features are being queried.

?

Range syntax

Container size features can be written with comparison forms such as min-width, or with range notation such as width >= 36rem. The important idea is still a comparison against the selected query container, not a new sizing algorithm.

?

Combining conditions

Container queries can combine conditions with the same boolean structure used by conditional query syntax. Keep the logical question separate from the component’s styling: first decide which container feature must be true, then write the smallest condition that expresses it.

?

Nested conditional rules

A container query can appear within other conditional CSS contexts. This does not merge the ownership of the conditions: each gate contributes its own test, and the nested rule participates only when every required condition allows it.

?

Style queries: a different kind of container condition

Scroll-state queries can react to scrolling state

The current CSS Conditional Rules Level 5 draft also lets a query container expose scroll state with `container-type: scroll-state`. Container queries can then test states such as `stuck`, `snapped`, `scrollable`, and `scrolled`. This stays with the container-query owner because the feature changes how a descendant is conditionally styled from its container context; Scroll Snap, Overflow, and Positioned Layout still own the underlying scrolling, snapping, overflow, and sticky-positioning models.

?

Container-query syntax is not limited to dimensions. Style queries can ask about styles associated with a query container. They are a developing part of the broader container-query area, so teach them as a separate capability rather than presenting them as the same stable baseline as size queries.

?

Container-relative length units

Container query length units let a declaration use the size of the query container as its reference. The unit family includes cqw and cqh for width and height, cqi and cqb for inline and block size, and cqmin and cqmax for the smaller and larger relevant dimensions.

?

?

The container unit family

Use cqw and cqh when you deliberately want physical width/height references; prefer cqi and cqb when the component should follow its logical inline/block dimensions. cqmin and cqmax select the smaller or larger of the relevant container dimensions.

?

Container units are values, not queries

A container-relative unit does not itself create a conditional rule. It produces a length relative to a query-container reference. That means a component can scale continuously with its container instead of switching only at discrete @container thresholds.

?

Containment is a prerequisite, not a second lesson

Container queries depend on containment concepts, but this lesson does not become the general CSS Containment lesson. Here you only need the containment needed to establish a query container. The Containment owner explains containment as a broader optimization and rendering model.

?

Container queries do not own layout algorithms

A query can change Grid, Flexbox, typography, or spacing, but the query lesson does not take ownership of those algorithms. Use the existing layout lessons as the places to learn what the changed declaration actually does.

?

Container queries versus media queries

Use @media when the condition is about the user agent or output environment, such as viewport or device features. Use @container when the condition is about the component’s query container. A component can respond to both, but each condition should answer a distinct question.

?

Container queries and custom properties

Custom properties can carry component configuration, but their inheritance behavior remains owned by the Custom Properties/Cascade curriculum. A container query can consume values without redefining how custom properties inherit or cascade.

?

Nested components

Nested query containers are useful when each component should respond to its own allocation. Name containers when you need a stable selection boundary; otherwise the nearest eligible container is used for an unnamed query.

?

Debugging a container query

When a container query appears not to work, change one variable at a time: confirm that an eligible query container exists, confirm the query selects the container you expect, confirm the feature value crosses the threshold, and only then inspect the nested declaration and its cascade.

?

Authoring rules

Choose the component boundary before choosing the breakpoint. Name containers when nested boundaries make selection ambiguous. Use container units for continuous relationships and @container conditions for discrete state changes. Keep media queries for environment-level concerns.

?

Specification status

Container-query functionality spans CSS Containment and Conditional Rules work. The W3C currently lists CSS Containment Level 3 as a Working Draft, while CSS Conditional Rules Level 5 is also a Working Draft. Container-relative units are part of the CSS values/units work. Treat developing pieces such as style queries with explicit status labels rather than presenting them as timeless guarantees.

The stable teaching core in this lesson is the component-level mental model: establish an appropriate query container, select it, evaluate a condition against it, and use container-relative values when continuous adaptation is more appropriate. Check current W3C status before relying on newer container-query features.

A practical decision tree

Ask: Is the condition about the viewport or user agent environment? Start with Media Queries. Is it about the available space of a component ancestor? Use Container Queries. Is it a continuous size relationship rather than a state switch? Consider a container-relative unit. Is the behavior actually about a layout algorithm, sizing algorithm, or containment optimization? Go to that owner instead.

?

Ownership boundaries

This lesson owns container-query evaluation and container-relative units. Media Queries owns environment-level conditional evaluation. Values and Units owns the general value/unit system. Sizing owns general sizing algorithms. Containment owns the broader containment model. Flexbox, Grid, and other layout lessons own the algorithms used by declarations that a container query may turn on.

Keeping these boundaries explicit prevents the curriculum from turning every adaptive example into another responsive-design lesson. The same component can be demonstrated in several lessons, but the algorithm or mechanism should be explained only by its primary owner.

Quick recap

A container query is a condition evaluated against an eligible ancestor query container. Establish the boundary with container-type, optionally name it with container-name, use @container for discrete conditions, and use cqw/cqh/cqi/cqb/cqmin/cqmax when a declaration needs a container-relative length. Then hand the actual layout, sizing, text, or containment behavior back to its primary curriculum owner.

?

?

?