CSS container queries let a component change its styling according to the space or other features of an ancestor container, rather than the browser viewport. For example, a card can switch to a two-column layout when its own container is wide enough—whether it appears in a main column, a sidebar, or a card grid.
What are CSS container queries?
Container queries apply styles to elements nested inside a specific container based on features of that container. The CSS Working Group distinguishes them from media queries: media queries test the user-agent or device environment, such as viewport dimensions or user preferences, while container queries can test elements within the document, including box dimensions and computed styles. See the MDN container queries guide and the CSS Containment Module Level 3 specification.
This makes container queries useful for reusable components. A media query can tell a card to change when the viewport gets wider; a container query can tell it to change when the card’s available space gets wider, regardless of the page layout around it.
How to write a size container query
For a size query, first establish a query container on an ancestor. Then add an @container rule for descendants whose styles should respond to it.
#1 Best Overall
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
.card-list {
container-type: inline-size;
}
@container (width > 40rem) {
.card {
display: grid;
grid-template-columns: 1fr 1fr;
}
}In this example, .card-list establishes the query context. When its width is greater than 40rem, the nested .card changes to a two-column grid. The query responds to the container, not the viewport.
Choose the containment type for the dimensions you need
container-type: inline-sizeenables queries on the container’s inline dimension. It is the usual choice for components that adapt to available width.container-type: sizeenables size queries on both inline and block dimensions. Use it when the component genuinely needs to respond to both axes.
The container shorthand can set a name and type together: container: cards / inline-size;.
Use supported size features and conditions
Size queries can test width, height, inline-size, block-size, aspect-ratio, and orientation. Their conditions use familiar media-query-style comparisons and logic, including ranges and the operators and, or, and not. Consult the MDN reference for syntax and feature details.
When to name a container
If multiple ancestors can serve as query containers, give the intended one a name. A named query selects a matching ancestor instead of allowing a nearer, unrelated container to control the component.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #3
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
.layout {
container: page / inline-size;
}
@container page (width > 60rem) {
.component {
/* styles for the page container */
}
}Here, page is the container name. Naming is particularly helpful in nested layouts, where a component may sit inside more than one eligible container.
How container queries differ from media queries
| Question | @media |
@container |
|---|---|---|
| What it measures | The viewport, device, or user-agent environment, such as viewport size or user preferences. | Features of an eligible ancestor container, such as its dimensions or computed styles. |
| What controls a component’s breakpoint | The page or device context. A component’s change is tied to that environment. | The space or feature of the container it occupies, so the same component can respond differently in different parts of a page. |
| What setup is needed | No container declaration is required. | Size queries require a size-containment context, commonly declared with container-type: inline-size. |
| Compatibility planning | Check support for the particular media feature and target browsers. | Check support for the specific container-query type; size queries have broader support than newer variants. |
Container query length units
Container query units express lengths as a percentage of dimensions on the relevant query container. They can size typography, spacing, or other dimensions in proportion to the component’s container.
| Unit | Relative dimension |
|---|---|
cqw |
1% of the container’s width |
cqh |
1% of the container’s height |
cqi |
1% of the container’s inline size |
cqb |
1% of the container’s block size |
cqmin |
1% of the smaller relevant dimension |
cqmax |
1% of the larger relevant dimension |
For example, 2cqi represents 2% of the query container’s inline size. See MDN’s container query documentation for the unit definitions.
Understand containment before adding it
Size containment changes sizing behavior: the container’s size is not determined in the ordinary way by its contents along the contained axis. That separation is necessary to avoid circular dependencies—for example, a container’s size affecting a descendant’s style that then changes the container’s size—and it lets browsers optimize layout. MDN explains this rationale in its container queries guide.
Recommended Free Tools
Before adding a query container to an existing component, check how its size is established and how the change affects intrinsic sizing, replaced elements, and fallback behavior. A query is only useful if the container still receives the dimensions the design expects.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Browser support and query variants
MDN’s reference describes the @container at-rule and the container and container-type properties as broadly established across browsers since February 2023. That broad availability does not mean every container-query variant has identical support. MDN also documents style queries, name-only queries, scroll-state queries, and anchored queries; style queries have narrower support than size queries. Can I Use publishes separate compatibility tables for size container queries and style queries.
For production code, check the exact query type against the browser versions your audience uses. Keep a sensible base style, and where older browsers matter, use feature detection or a media-query fallback appropriate to the design. Do not assume support for size queries establishes support for style, scroll-state, or anchored queries.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →
