Use a container query when a component needs to respond to its own space

A card may occupy the full page in one place and a narrow sidebar in another. A viewport media query sees the same browser width in both cases. A container query can instead respond to the space offered by the card’s surrounding layout.

MDN’s container-query guide explains size-query containers and the relationship between a container and its descendants. Establish the relevant container before writing a rule that expects to query it.

A compact starting example

This illustrative CSS switches a card from a vertical arrangement to two columns when its named container is wide enough:

.card-slot {
  container-type: inline-size;
  container-name: cardspace;
}
.card {
  display: grid;
  gap: 1rem;
}
@container cardspace (min-width: 32rem) {
  .card { grid-template-columns: 1fr 2fr; }
}

Place the card inside the element with the card-slot class. The queried size belongs to that surrounding container; the rule changes the descendant card. The threshold is an example to test with real content, not a standard size every card should use.

Start with a usable base layout outside the query. Then add the wider arrangement as an enhancement. Check long headings, translated text, missing images and enlarged text before deciding the component is finished.

Be deliberate about where containment is introduced. Adding containers indiscriminately can change sizing behaviour and make it harder to understand which ancestor a query uses. A named container helps express the intended relationship when several containers are nested.

Test the component in two homes

Render the same card in a wide article area and in a narrow side panel at the same browser width. Resize each surrounding region if your development setup permits it. The card should respond to the available region rather than requiring a separate “sidebar version” full of duplicated rules.

Media queries remain useful for page-wide conditions and user preferences. Container queries solve a more local question: how should this component use the room it has? Choose the mechanism that matches that question, then verify keyboard access, reading order and overflow in the finished layout.