A product card shown inside a narrow sidebar and the same card shown at full width probably should not look alike: one would benefit from stacking its image and text, the other from placing them side by side. A Media query cannot make that distinction, since it only knows the width of the whole screen, not the width of the block where the card actually sits.
The container query was built precisely for that case: it reacts to the size of the component's direct parent, not the size of the window.
Definition
A container query is an @container rule that applies a block of CSS based on the width, or sometimes the height, of an ancestor declared as a container. It lets a component change appearance based on the space actually allocated to it, independently of the screen size displaying the page.
Syntax
Two steps are needed. First, the parent element must be declared a container with container-type. Then, the @container rule targets that container and applies its CSS once the width condition is met.
.card-zone {
container-type: inline-size;
container-name: card;
}
.card {
display: flex;
flex-direction: column;
}
@container card (min-width: 400px) {
.card {
flex-direction: row;
gap: 16px;
}
}Without the container-type: inline-size line, the following @container rule never fires: this is the most common mistake when first meeting this feature.
Media query versus container query
The two look alike in their syntax, but they answer a different question.
| Media query | Container query |
|---|---|
| Reacts to the width of the whole window | Reacts to the width of the parent block |
| The same component behaves alike everywhere on the page | The same component adapts to where it sits |
| No prior declaration required | The parent must be declared with container-type |
The classic pitfall
Forgetting to declare the container is not the only trap: an element cannot be its own container for its own children while also reacting to a container query defined on itself. A separate ancestor must carry container-type, and the element styled by @container sits inside that ancestor, never confused with it.
container-type is set on the parent before wondering why an @container rule will not fire. It is the most common oversight, and it produces no visible error in the console; the rule is simply ignored silently.A typical use case
The most cited case is a reusable component placed in several contexts within the same interface: a card shown both in a results grid and in a sidebar of suggestions, or a Flexbox component that has to stack in a narrow space. The component itself only needs one CSS definition, sensitive to the space it is given, instead of a separate variant for every context it appears in.
A component library shared across several projects benefits from this approach in particular: each component becomes responsible for its own adaptation, without ever forcing the page that uses it to know in advance which context it will be placed in.
Frequently asked questions
No. Some decisions, such as changing the default font based on screen orientation or detecting the system's dark mode, genuinely depend on the device and stay the media query's job. The container query is added on top for cases where the component's own space, not the screen's, should decide.
Yes, a component can react to its direct container while that container itself reacts to a wider one, as long as each level carries its own container-name so the right rule targets the right element without ambiguity.
The principle is identical: the threshold chosen in min-width should match the point where the component becomes uncomfortable inside its container, found by shrinking the parent, not an arbitrary value copied from another project.