Learn how CSS container queries let cards, menus, and other components adapt to the space around them, with clear examples and common mistakes to avoid.
A card may have plenty of room on a wide page, then become cramped in a sidebar. A traditional media query usually responds to the size of the browser window, not the space available to that card. CSS container queries solve this by letting a component change based on the size of its own container.
This makes it easier to reuse the same component in different parts of a site. In this guide, you will learn how to set up CSS container queries, write a simple layout change, and avoid common problems. You will also see when a regular media query is still the better choice.
A container query applies CSS when a chosen container reaches a certain size. Instead of asking, “How wide is the browser window?”, it asks, “How wide is this part of the page?”
That difference matters when a component can appear in several places. For example, a product card might sit in a wide row on one page and in a narrow sidebar on another. With a container query, the card can change its layout to suit the space it actually has.
Container queries are often used to adjust the direction of a layout, the size of text, or whether an image sits beside or above its text. They do not replace every media query. They give you another tool for choosing the right kind of response.
Use a container query when a component should respond to the space provided by its parent, no matter where that component appears. Common examples include:
A media query is often a better fit when the change depends on the whole screen or device. For example, you might change the main page layout when the browser becomes wide enough to show a sidebar. You can use both kinds of queries on the same page: media queries for the overall layout, and container queries for components inside it.
A container query needs two parts. First, tell an element to act as a query container. Then write an @container rule that checks the container’s size.
Here is a basic example. The class product-area is the container. The container-type property tells the browser that styles inside it may depend on its width.
.product-area {
container-type: inline-size;
}
inline-size means the query checks the container’s width in a usual left-to-right page. It uses the page’s writing direction, so it can also work in languages that flow in a different direction.
You can also give the container a name. A name is useful when a page has several containers and you want to make clear which one a rule should check.
.product-area {
container-type: inline-size;
container-name: product;
}
Now you can write a query that changes the product card when the named container is at least 32rem wide.
@container product (min-width: 32rem) {
.product-card {
display: grid;
grid-template-columns: 1fr 2fr;
gap: 1rem;
}
}
The rule inside the braces applies when the product container is wide enough. The card then uses two columns: one for an image and one for its details. Below that width, the card keeps its usual layout.
If you do not need a name, you can leave out container-name and use an unnamed query:
.card-list {
container-type: inline-size;
}
@container (min-width: 32rem) {
.product-card {
grid-template-columns: 1fr 2fr;
}
}
An unnamed query uses the nearest ancestor that can act as a size container. A named query makes the target easier to spot, especially in a larger stylesheet.
This example starts with a simple card that works in a narrow space. When its container becomes wider, the image and text move into columns.
.card-list {
container-type: inline-size;
container-name: cards;
}
.product-card {
display: grid;
gap: 1rem;
padding: 1rem;
border: 1px solid #d6d6d6;
border-radius: 0.75rem;
}
.product-card img {
display: block;
width: 100%;
height: auto;
border-radius: 0.5rem;
}
@container cards (min-width: 34rem) {
.product-card {
grid-template-columns: minmax(8rem, 1fr) 2fr;
align-items: center;
}
}
The base styles come first, so the card has a useful layout even before the query takes effect. The query adds the two-column layout only when the container has enough space. The image uses a flexible width and keeps its proportions because its height is set to auto.
Notice that the query checks .card-list, while the rule styles .product-card, which is inside that container. A container query does not let an element query its own size. The container must be an ancestor of the element being changed.
A breakpoint is the size where the design changes. With container queries, choose it based on the needs of the component, not on a popular phone or tablet size.
Start with the narrow layout. Then make the container wider in your browser or design preview. When the card has enough room for another column, note that width and use it as the breakpoint. This helps avoid a layout that changes too early and leaves text squeezed beside an image.
For example, a card with a long title may need more room than a card with only a short label. Test real content, not just a neat sample. If the layout still feels crowded, raise the breakpoint or simplify the wider layout.
Container queries also provide special units that scale with the container. The most common is cqi, which means one percent of the container’s inline size. In a typical horizontal layout, it acts much like one percent of the container’s width.
.card-title {
font-size: clamp(1.1rem, 4cqi, 1.8rem);
}
clamp() keeps the text size between a minimum and a maximum. Here, the title can grow as the container grows, but it will not become smaller than 1.1rem or larger than 1.8rem. This can be useful for flexible headings, though a fixed size may be easier to read in some designs.
Container units depend on a suitable query container. If the browser cannot find one, it may use a small fallback value based on the viewport. For that reason, test the component in the real layout and avoid using container units without checking how they behave outside the expected container.
A query will not work as expected if no suitable ancestor has a container type. Add container-type: inline-size to the element whose width should control the change. Then check that the styled element is inside it.
The query checks an ancestor, not the element that has the query container setting. If you need to change the card, put the container setting on a wrapper around the card, then write the rule for the card.
An unnamed query may use the nearest eligible container, which is not always the one you intended. If a component sits inside several containers, give the right one a name and refer to it in the query. This makes the connection easier to understand later.
Do not build only the wide version and try to squeeze it down. Start with a layout that works in a narrow container. Add columns, extra spacing, or larger text only when there is enough room.
A card does not know whether it is on a phone or a laptop. It only has a certain amount of space. Test how the component behaves at different widths and choose a point where its content has room to change.
Container queries work in current major browsers, but older browsers may not support them. If your visitors may use older software, check the browser support you need before relying on the feature. Keep the default layout useful on its own. The default styles should still show the content clearly if the query is ignored.
Also test the component in more than one place. A reusable card may be wide in the main content and narrow in a sidebar. Those different settings are exactly where container queries can make a noticeable difference.
| Question | Container query | Media query |
|---|---|---|
| What does it check? | The size of a chosen ancestor container | The browser viewport or other device conditions |
| Best suited for | Reusable components that appear in different spaces | Page-wide changes, such as adding a sidebar |
| Example | Change a card from stacked to side-by-side | Change the main page from one column to two |
Neither option is always better. Ask what should control the change. If the answer is the component’s local space, try a container query. If the answer is the overall screen or a device setting, a media query may be more direct.
Yes. A query without a name uses the nearest ancestor that is set up as a suitable container. Naming containers is optional, but it can make complex layouts clearer and help prevent a rule from checking the wrong ancestor.
No. They are one part of responsive design, which means making a site work across different sizes and settings. You can combine container queries with flexible layouts, media queries, and sensible default styles.
No. A size query checks the container and applies styles to elements inside it. It is not a way for a box to change its own size based on its measured width. Set the container’s size through its parent layout, such as Grid or Flexbox, and let the query adjust its contents.
It allows the browser to use the container’s inline size for size queries. In a common left-to-right layout, that is its width. It also creates a boundary for some layout calculations, so test the surrounding design after adding it.
CSS container queries give components a way to respond to the space they actually receive. That is especially helpful when the same card, menu, or content block appears in several layouts.
Start with a solid narrow layout, mark a parent as a container, and add a query when the component has room to improve. Keep the rules focused, test real content, and use media queries for changes that belong to the whole page. With that approach, container queries can make reusable designs easier to build and maintain.
No account yet?
Create an Account
