CSS Container Queries: style components by their container, not the viewport

Container queries let an element respond to the size of its parent container instead of the size of the whole viewport. That is the missing piece that finally makes a component reusable: the same card can lay out one way in a narrow sidebar and another way in a wide main column — on the same page, at the same screen width.

Why media queries were not enough

A media query asks one question: how wide is the viewport? But a component does not know how wide the viewport is — it knows how much room it was given. A card dropped into a 300px sidebar and the same card in a 900px grid cell need different layouts, yet the viewport width is identical. Container queries fix exactly this.

Step 1: declare a containment context

You query a container, so first you have to mark an element as a container with container-type:

.card-wrapper {
  container-type: inline-size;
}

inline-size means "let me query the inline (usually horizontal) dimension" — the most common choice. size queries both dimensions, and normal turns containment off.

Step 2: query it with @container

Now any descendant of .card-wrapper can adapt based on the wrapper's width:

.card {
  display: grid;
  gap: 1rem;
}

@container (min-width: 400px) {
  .card {
    grid-template-columns: 150px 1fr;
  }
}

When the wrapper is at least 400px wide, the card switches to a two-column layout. Drop that same markup anywhere on the page and it adapts to wherever it lands — no page-level media queries needed.

Naming containers

When containers are nested, give them names with container-name so a query targets the right one:

.layout { container: layout / inline-size; } /* name / type shorthand */

@container layout (min-width: 600px) {
  .card { /* responds to .layout, not a closer container */ }
}

Container query units

Container queries also unlock units relative to the container instead of the viewport: cqw (1% of the container's width), cqh, cqi (inline) and cqb (block). Fluid typography that scales with its container becomes a one-liner:

.card h2 {
  font-size: clamp(1rem, 5cqi, 2rem);
}

Container queries vs media queries

	Media query	Container query
Measures	Viewport / device	Nearest sized ancestor
Setup needed	None	container-type on a parent
Best for	Page-level layout	Reusable components
Units	vw, vh	cqw, cqi, ...

Browser support

Size container queries are supported across current Chrome, Edge, Firefox and Safari. They are not a replacement for media queries — use media queries for the overall page structure and container queries for components that must be portable. The two work well together.

The mental shift is small but powerful: stop asking "how big is the screen?" and start asking "how much room does this component have?" That single change is what makes a design system's components genuinely drop-in anywhere.