Skip to content
Tutorials Center
My learning

Topics

Lesson 84 of 139 ยท Responsive Design

Container Queries

Make components respond to their own space with CSS container queries. Learn container-type, @container, named containers, cqi units and style queries.

Media queries ask about the whole viewport. That works for page-level layout, but components don't live in the viewport; they live in a column, a sidebar, a grid cell or a modal. A card in a narrow sidebar on a huge monitor is still a narrow card, and a media query can't tell.

Container queries fix this. They let an element respond to the size of a container around it. You design a component once, and it adapts to wherever you put it: wide in the main column, compact in the sidebar, and everything in between, with no knowledge of the page around it.

Two steps: declare a container, then query it

First, mark an element as a query container with container-type:

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

Then write an @container rule. It looks just like a media query, but it measures the nearest ancestor container instead of the viewport:

CSS
@container (width >= 400px) {
  .card {
    display: grid;
    grid-template-columns: 120px 1fr;
  }
}

The .card inside .card-wrapper switches to two columns when the wrapper is at least 400px wide, whatever the screen size. The same range syntax you learned in Media Queries works here, along with the older min-width style.

There is one important rule: a container can't style itself with its own query. The @container rule styles the container's descendants. That's why you usually put container-type on a wrapper and style the element inside it.

Try it: a resizable container

In the demo below, the dashed box is the container. It has resize: horizontal, so you can drag its bottom-right corner to change its width. The card inside responds to the box, not to the preview pane.

A card that responds to its container

container-type values

There are three values:

  • inline-size: you can query the container's inline size (its width, in horizontal writing). This is the one you'll use almost every time.
  • size: you can query both width and height. Because the height must be known without looking at the content, the container no longer grows to fit its children. You must give it a height yourself, or it collapses. Use it only for boxes with a fixed size.
  • normal: the default. The element isn't a size container, though it can still be used for style queries (see below).

The catch with inline-size

To make container queries possible, the browser has to know the container's width without asking its children. So container-type: inline-size applies size containment in the inline direction: the container ignores its content when working out its own width.

In most layouts that's fine, because block elements and grid cells get their width from their parent anyway. But a container that normally shrinks to fit its content will shrink to nothing instead. Watch out for containers that are:

  • floated, position: absolute, or display: inline-block;
  • flex items with no flex-basis or width (they size from content);
  • grid items in an auto or max-content track.

The fix is to give such a container a width from outside, such as flex: 1, a width, or a 1fr grid track. If a component mysteriously disappears after you add container-type, this is almost always why.

The same component in two places

This is where container queries shine. Below, one card component sits in a narrow sidebar and in a wide main column. The CSS for the card is identical; each copy adapts to its own container.

One component, two contexts

The sidebar is only 140px wide, so its card stacks. The main column is wider, so its cards line up in a row. Make the preview narrow enough and the main cards stack too. A media query could never do this, because both cards share the same viewport.

Named containers

@container measures the nearest ancestor that is a size container. In nested layouts, that may not be the one you want. Give containers a name with container-name, and target that name in the query:

CSS
.sidebar {
  container-type: inline-size;
  container-name: sidebar;
}

@container sidebar (width < 200px) {
  .nav-label { display: none; }
}

The container shorthand sets both at once, with the name first and a slash:

CSS
.sidebar { container: sidebar / inline-size; }

An element can have several names separated by spaces, which is handy when one container plays more than one role.

Container query units

Container queries come with their own length units, which are percentages of the query container's size:

Unit 1 unit equals
cqi 1% of the container's inline size (width in horizontal text)
cqb 1% of the container's block size (height)
cqw / cqh 1% of the container's width / height
cqmin / cqmax the smaller / larger of cqi and cqb

They work like viewport units, but relative to the container. Prefer cqi over cqw so your code also works in vertical writing modes. Combined with clamp(), they make text and spacing that scale smoothly with the component:

Sizing with cqi units

If there is no query container around an element, container units fall back to the small viewport units (as if the viewport were the container). The Fluid Typography lesson compares viewport units and container units for text.

Style queries

Size isn't the only thing you can query. Style queries test the computed value of a custom property on a container:

CSS
.card-list { --layout: compact; }

@container style(--layout: compact) {
  .card { padding: 6px; font-size: 0.9rem; }
}

Every element is a style container by default, so you don't need container-type for these; the query looks at the nearest ancestor (or a named container). This lets a parent switch its children between variants with one custom property, without adding classes to each child.

Support: size container queries and container units have worked in all major browsers since 2023, so you can use them freely. Style queries for custom properties work in Chromium-based browsers and Safari 18 and later, and since 2026 in Firefox too (Baseline newly available since May 2026), so older browser versions may still lack them. Treat style queries as an enhancement: make sure the component still looks fine if the query is ignored.

Media queries or container queries?

They work together. A good rule of thumb:

  • Media queries for page-level layout (where the sidebar goes, how many page columns there are) and for user and device features like prefers-reduced-motion and hover, which containers know nothing about.
  • Container queries for components that might appear in different places: cards, widgets, media objects, form groups.

Start with intrinsic layout, add container queries for components and media queries for the page shell. The Dashboard project at the end of the course combines all three.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does container-type: inline-size do?

    It turns the element into a size container for the inline axis, so @container rules can style its descendants based on its width.
  2. 2. Why might a container collapse to zero width after you add container-type: inline-size?

    Size containment means the container works out its inline size without looking at its children. Shrink-to-fit containers such as floats or content-sized flex items need a width from outside.
  3. 3. Which rule targets a container named sidebar?

    The container's name goes between @container and the condition. Name it with container-name or the container shorthand.
  4. 4. What is 10cqi inside a query container that is 500px wide (horizontal text)?

    1cqi is 1% of the container's inline size, so 10cqi is 10% of 500px, which is 50px.
  5. 5. Which job still needs a media query rather than a container query?

    User preferences and device features such as prefers-reduced-motion are only available to media queries. Containers only know their size and styles.

Summary

  • Container queries let components respond to the size of a container instead of the viewport.
  • Declare a container with container-type: inline-size, then style its descendants with @container (width >= ...).
  • A container can't query itself, and size containment can collapse containers that are sized from their content.
  • Use container-name (or container: name / inline-size) to target a specific ancestor.
  • cqi, cqb, cqmin and cqmax are lengths relative to the container, great inside clamp().
  • Style queries test custom properties; they are not yet supported everywhere, so use them as an enhancement.

Next: Fluid Typography, where you make text scale smoothly with clamp() and viewport or container units.