Skip to content

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)
  1. Media query vs. CSS container queries
  2. container-type
  3. @container
  4. A product card in three contexts
  5. Container query units
  6. Browser support
  7. Common mistakes
  8. Frequently asked questions
  9. Checklist

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:

SlotWith @containerWith @media (1280 px window)
240 px1 column, 16 px title3 columns
480 px2 columns, button under the title3 columns
720 px3 columns, 21.6 px title3 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:

the same card in three containers of different width240 px480 px720 px1 column2 columns3 columnsbasemin-width: 24remmin-width: 36rem@container card (min-width: …) { .card { grid-template-columns: … } }one CSS, three layouts, no window resizemeasured locally in Chromium 151: 1, 2 and 3 columns with the window at 1280 px

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;
}
  1. The first block turns .card-slot into a container that is queried by its width.
  2. container-name: card names it, so an @container card targets this container and no other.
  3. The second block is the container: name / type shorthand; 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.

the query measures the container and styles its descendants.card-slotcontainer: card / inline-size.cardgrid-template-columnsfont-size× does not reach the containermeasured: outline-style none@container card(min-width: 24rem)styles .carda container cannot restyle itselfmeasured in Chromium 151: a rule on the container itself does not apply

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 with container-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>
  1. .card-slot is the container; whoever places the card sets it.
  2. The image has width and height to reserve its space before it loads.
  3. 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);
  }
}
  1. .card-slot is the container, named card and queried by width.
  2. .card is a grid; with no query, grid-template-areas stacks image, title and button in one column.
  3. .card__img fills the width and aspect-ratio: 4 / 3 keeps its proportion, so there is no layout shift when the photo loads.
  4. .card__title and .card__cta take their place with grid-area; the area names are the ones in grid-template-areas.
  5. From 24rem (384 px at a 16 px base font), two columns: an 8rem image on the left spanning two rows, title on top and button below.
  6. From 36rem (576 px), three columns in a single row: a 12rem image, then title and button on the right, vertically centered.
  7. 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.
  8. Both @container blocks use min-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.

each piece of container queries and since when it workspiecewhat it doesremembercontainer-type: inline-sizequeries the widthwidth comes from contextcontainer-type: sizequeries width and heightcollapses without a sizecontainer-type: normalno size queriesthe default value@container card (…)named queryfinds the ancestor cardcqi · cqw · cqb · cqh1% of the containerno container: sv* unitBaselineWidely availablesince February 2023available in all browsers since 2023source: MDN, container-type and container queries · Nov 12, 2026

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-type on the element you want to change. An @container rule does not style its own container (measured: the outline did not apply). Declare the container on the slot.
  • Using size without a size. With size containment and no height or width from context, the element collapses. inline-size is 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 cqi without a container. It falls back to the window: I measured 128px for 10cqi in a 1280 px window.
  • Images without width and height. 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 @container carries the container's name.
  • The base layout, with no queries, works in one column.
  • The image has width, height and aspect-ratio.
  • Every cqi sits 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

Luis Morales

Luis Morales

Frontend and Shopify developer, EcomLabs

@luismoralesdev on Instagram

Published November 12, 2026 · updated November 18, 2026

← Blog