CSS Responsive Design
Container Queries
Adapt a component to the space provided by its container instead of the size of the viewport. You will establish named query containers, write size and style queries, use container-relative units, and decide when media queries remain appropriate.
Container queries condition a component’s styles on an ancestor container rather than on the viewport. The component can therefore adapt to the space it actually receives.
A card may appear in a wide main column, a narrow sidebar, or a dashboard cell while the viewport remains unchanged. Viewport breakpoints cannot describe those situations reliably. By establishing an inline-size query container, the card can switch layout at the point where its own content and available width require it. This topic also connects with CSS Media Queries and Feature Queries.
Establish a query container
Example
css
.card-region {
container: cards / inline-size;
}
.card {
display: grid;
gap: 1rem;
}
@container cards (width >= 34rem) {
.card {
grid-template-columns: 10rem 1fr;
}
}Size queries require containment on the queried axis. Naming the container prevents an inner component from accidentally querying the wrong ancestor.
Container query units
Example
css
.card__title {
font-size: clamp(1.2rem, 4cqi, 2rem);
}cqi is one percent of the query container’s inline size. Other units include cqw, cqh, cqb, cqmin, and cqmax.
Style queries
Example
css
@container style(--featured: true) {
.card { border-color: gold; }
}Query a container's scroll state
Scroll-state queries can respond when a sticky element is stuck, an item is snapped, or a container can still scroll in a direction. Declare a scroll-state query container, then test its state from an @container rule.
Example
css
.section-heading {
position: sticky;
inset-block-start: 0;
container: section-heading / scroll-state;
}
@container section-heading scroll-state(stuck: top) {
.section-heading__content {
box-shadow: 0 0.35rem 0.8rem rgb(15 23 42 / 0.18);
}
}Container Query Reference
| Syntax | Purpose | Example |
|---|---|---|
| container-type | Establishes a size query container. | container-type: inline-size |
| container-name | Names a query container. | container-name: card |
| @container | Applies rules according to container conditions. | @container card (width > 30rem) |
| cqw | Represents one percent of the query container's width. | font-size: 4cqw |
| scroll-state() | Tests whether a container is stuck, snapped, scrolled, or scrollable. | scroll-state(stuck: top) |
Complete Example
Run the complete document below in the Try It editor. Resize the preview or interact with the controls where the example calls for it.
Complete runnable example
html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Container Queries example</title>
<style>
* { box-sizing: border-box; }
body {
margin: 0;
padding: 2rem;
font-family: system-ui, sans-serif;
line-height: 1.5;
}
main { max-width: 70rem; margin-inline: auto; }
article, section, aside, form, .card, .panel {
padding: 1rem;
border: 1px solid #cbd5e1;
border-radius: 0.6rem;
}
.card-region {
container: cards / inline-size;
}
.card {
display: grid;
gap: 1rem;
}
@container cards (width >= 34rem) {
.card {
grid-template-columns: 10rem 1fr;
}
}
.card__title {
font-size: clamp(1.2rem, 4cqi, 2rem);
}
@container style(--featured: true) {
.card { border-color: gold; }
}
.section-heading {
position: sticky;
inset-block-start: 0;
container: section-heading / scroll-state;
}
@container section-heading scroll-state(stuck: top) {
.section-heading__content {
box-shadow: 0 0.35rem 0.8rem rgb(15 23 42 / 0.18);
}
}
</style>
</head>
<body>
<main class="card-region"><article class="card"><div aria-hidden="true">◼</div><section><h1 class="card__title">Container-aware card</h1><p>Resize the preview. The card responds to its container.</p></section></article></main>
</body>
</html>Browser Support
Feature | Chrome | Edge | Firefox | Safari |
|---|---|---|---|---|
| @container size queries | 105 | 105 | 110 | 16 |
| Scroll-state queries | 133 | 133 | No | No |
Versions show the first stable desktop release with unprefixed support. Data source: MDN Browser Compatibility Data 8.0.8. A partial-support note is included where it changes how the example behaves.
Notes
- Use media queries for page- or device-level conditions. Use container queries when the same component can appear in differently sized regions.
- Scroll-state queries still have limited browser support. Keep the ordinary sticky or snapped presentation complete, and use the query only to add feedback.
- Test the example with real content, keyboard input, browser zoom, and the narrowest layout your project supports.
- Use a fallback when the support table shows that one of your required browsers predates the feature.
Conclusion
Container queries make a component respond to the space it actually receives.
Name containers when nesting could make the queried ancestor ambiguous, and keep query thresholds tied to component behavior rather than common device widths. Continue using media queries for page-wide environment conditions such as viewport layout, printing, or user preferences.