CSS container queries: one product card that fits any container
From the work/ 9 min read
container-type, @container and cqi units explained with one product card that goes from one to three columns in a grid, a sidebar or a cart. Tested in Chromium 151.
- Themes
- Performance
- JavaScript
In this article (9)
CSS container queries apply styles based on the width of a component's container instead of the window. Declare container-type: inline-size on the parent, write @container (min-width: 24rem), and the same product card lays itself out in a grid, a sidebar or a cart. They work in every browser since February 2023.
Here is the full card, with the CSS I tested locally with Playwright and Chromium 151: three copies in slots of 240, 480 and 720 px inside a fixed 1280 px window. The numbers below were measured, not assumed.
Media query vs. CSS container queries
A media query asks about the window: its width, its orientation, whether the user prefers less motion. A container query asks about the slot the component lives in. The difference matters when one card shows up in a collection grid, in a sidebar and in a cart: the window is the same size in all three places, but the slot is not.
I measured it with the same card in three slots and a 1280 px window:
| Slot | With @container | With @media (1280 px window) |
|---|---|---|
| 240 px | 1 column, 16 px title | 3 columns |
| 480 px | 2 columns, button under the title | 3 columns |
| 720 px | 3 columns, 21.6 px title | 3 columns |
With @media, the card picked three columns in all three slots, because the window was the same. With @container, each slot got its own layout:
Scroll the figure sideways to see all of it
Media queries remain the tool for what depends on the page or the user: global navigation, the main grid, prefers-reduced-motion. Container queries are for the component.
container-type
For an element to be queried, you turn it into a container with container-type. According to MDN, three values matter here:
inline-size: queries the inline axis, which is the width in horizontal text. It applies style and inline-size containment: the container's width is computed without looking at its children.size: queries width and height. It applies size containment on both axes; without an explicit or contextual size, the element collapses.normal: the default. It is not a container for size queries, but it works for style queries and name-only queries.
Most of the time you want inline-size. The minimum for a card:
.card-slot {
container-type: inline-size;
container-name: card;
}
/* the same, in shorthand */
.card-slot {
container: card / inline-size;
}
- The first block turns
.card-slotinto a container that is queried by its width. container-name: cardnames it, so an@container cardtargets this container and no other.- The second block is the
container: name / typeshorthand; use one or the other, not both.
Because the width does not come from the children, it has to come from context: a block-level element that stretches to its parent's width, or an explicit width. A container with no width of its own does not work.
There is one more rule, and I measured it: an @container rule cannot style the container itself, only its descendants. I put an outline on .card-slot inside an @container card and outline-style stayed none. That is why the container is the slot, not the card.
Scroll the figure sideways to see all of it
@container
The query is written like a media query with an optional name. MDN distinguishes two forms:
- Unnamed:
@container (min-width: 24rem)targets the nearest ancestor that is a container. - Named:
@container card (min-width: 24rem)targets the container withcontainer-name: card.
Use a name. In a theme, there may be another ancestor with container-type between your card and the page (a section, a carousel), and an unnamed query will latch onto that one. MDN also accepts the range syntax, like @container (width > 700px); I use min-width out of habit, and it is just as valid.
A product card in three contexts
The HTML is a card inside a slot. The slot is what the collection, the carousel or the cart controls; the card does not know where it is:
<div class="card-slot">
<article class="card">
<img class="card__img" src="/shirt.jpg" alt="Cotton t-shirt" width="400" height="300">
<h3 class="card__title">Cotton t-shirt</h3>
<button class="card__cta" type="button">Add to cart</button>
</article>
</div>
.card-slotis the container; whoever places the card sets it.- The image has
widthandheightto reserve its space before it loads. - Title and button are direct children of the card, so they can be placed with
grid-area.
And the CSS, the one I ran in Chromium 151:
.card-slot {
container: card / inline-size;
}
.card {
display: grid;
grid-template-areas: "img" "title" "cta";
gap: 0.75rem;
padding: 0.75rem;
border: 1px solid #bbb;
}
.card__img {
grid-area: img;
width: 100%;
height: auto;
aspect-ratio: 4 / 3;
object-fit: cover;
}
.card__title {
grid-area: title;
margin: 0;
font-size: 1rem;
}
.card__cta {
grid-area: cta;
}
@container card (min-width: 24rem) {
.card {
grid-template-columns: 8rem 1fr;
grid-template-areas: "img title" "img cta";
align-items: start;
}
}
@container card (min-width: 36rem) {
.card {
grid-template-columns: 12rem 1fr auto;
grid-template-areas: "img title cta";
align-items: center;
}
.card__title {
font-size: clamp(1.125rem, 3cqi, 1.5rem);
}
}
.card-slotis the container, namedcardand queried by width..cardis a grid; with no query,grid-template-areasstacks image, title and button in one column..card__imgfills the width andaspect-ratio: 4 / 3keeps its proportion, so there is no layout shift when the photo loads..card__titleand.card__ctatake their place withgrid-area; the area names are the ones ingrid-template-areas.- From
24rem(384 px at a 16 px base font), two columns: an8remimage on the left spanning two rows, title on top and button below. - From
36rem(576 px), three columns in a single row: a12remimage, then title and button on the right, vertically centered. - In that same block, the title grows with
clamp(1.125rem, 3cqi, 1.5rem): 3% of the container's width, between 18 and 24 px. - Both
@containerblocks usemin-width, so the base layout is the one-column one: a browser that does not understand them shows it as is.
In a Shopify theme the split is the same: the card snippet only carries the CSS of .card, and the .card-slot slot is declared by the template that places it. And the image with dimensions is the same principle as in how to fix CLS from a cookie banner: reserve the space before the content arrives.
Container query units
MDN defines six units relative to the container: cqw and cqh are 1% of its width and height; cqi and cqb, 1% of its inline and block size; cqmin and cqmax, the smaller and larger of cqi and cqb. They work for descendants of a container whose container-type is size or inline-size.
I measured two cases with font-size: 10cqi:
- Inside a 480 px container:
48px, 10% of the container. - With no container at all, in a 1280 px window:
128px. MDN says it: with no eligible container, the unit falls back to the small viewport unit for that axis.
That is the first thing to watch with cqi: if you forget the container-type, the text scales with the window and nothing warns you. In the card, 3cqi gave 21.6 px in the 720 px slot, which is 3% of 720.
Browser support
The container-type page on MDN marks the feature as Baseline "Widely available": available across browsers since February 2023 (I read it on November 12, 2026). MDN adds that some parts may have varying levels of support; for example the scroll-state value, which I do not use here. If you need it, check its table.
Scroll the figure sideways to see all of it
For a browser that does not support @container, it ignores those blocks and keeps the base layout. If you want an explicit alternative, MDN suggests a grid with a media query.
Common mistakes
- Putting
container-typeon the element you want to change. An@containerrule does not style its own container (measured: theoutlinedid not apply). Declare the container on the slot. - Using
sizewithout a size. With size containment and no height or width from context, the element collapses.inline-sizeis almost always enough. - A container with no width of its own. The width has to come from context or from a
width; the children do not count. - Unnamed queries with nested containers. They latch onto the nearest ancestor, which may not be the one you mean.
- Using
cqiwithout a container. It falls back to the window: I measured128pxfor10cqiin a 1280 px window. - Images without
widthandheight. When the columns change, the card jumps when the photo arrives.
Frequently asked questions
Do container queries work in every browser?
According to MDN, container-type has been available across browsers since February 2023 and is listed as Baseline "Widely available" (checked November 12, 2026). Some parts, like scroll-state, have a different level of support.
Do they replace media queries?
No. Media queries remain the tool for what depends on the window or the user, like global navigation or prefers-reduced-motion. Container queries are for components that live in slots of different sizes.
Can I query the height?
Yes, with container-type: size, which queries width and height. But it applies size containment on both axes and the element collapses if the context does not give it a size; for cards, inline-size is the usual choice.
Where do I declare the container in a theme?
On the slot where the card is placed (the grid item, the carousel slide, the cart line), not on the card. That way each place decides its width and the card only reacts.
Checklist
- The container is the card's slot, not the card, and has
container: name / inline-size. - The container has a width that comes from context or from a
width. - Every
@containercarries the container's name. - The base layout, with no queries, works in one column.
- The image has
width,heightandaspect-ratio. - Every
cqisits inside a container. - I tested the card in at least three slot widths with the window fixed.
If the card carries large images, also read how to fix a slow LCP caused by the hero image, and to avoid jumps while loading, how to fix CLS from a cookie banner. The sources are MDN's pages on container queries and container-type.
Saw this on Instagram? Comment CONTAINER on the Reel and I'll send you the guide.
Written by

Published November 12, 2026 · updated November 18, 2026