CSS container queries: components that respond to their own space

Media queries ask about the viewport. But a card in a sidebar and the same card in a wide grid need different layouts at the same viewport width. Container queries let a component respond to the size of its container instead.

Size queries

Declare a container, then query it.

1.card-wrapper {
2  container-type: inline-size;
3  container-name: card;
4}
5

6.card {
7  display: grid;
8  gap: 1rem;
9}
10

11@container card (min-width: 480px) {
12  .card {
13    grid-template-columns: 160px 1fr;
14  }
15}

The same .card markup now stacks in a narrow sidebar and goes side by side in a wide column, wherever you place it. inline-size is almost always what you want; it only tracks the container's width.

Container query units

Units like cqi (1% of the container's inline size) let you scale things relative to the container.

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

Style queries

You can also query a container's custom properties. This is useful for variants and theming.

1.panel {
2  --tone: neutral;
3}
4.panel.danger {
5  --tone: danger;
6}
7

8@container style(--tone: danger) {
9  .panel-title {
10    color: #b91c1c;
11  }
12}

Support for style queries on custom properties is not as universal as for size queries. Check caniuse before relying on it and provide a sensible default.

Scroll-state queries

Chromium (133+) supports querying scroll state, for example styling a sticky header only when it is stuck:

1.header-wrap {
2  container-type: scroll-state;
3  position: sticky;
4  top: 0;
5}
6

7@container scroll-state(stuck: top) {
8  .header {
9    box-shadow: 0 2px 8px rgb(0 0 0 / 0.15);
10  }
11}

Firefox and Safari do not support this yet, so treat it as progressive enhancement: the page must look fine without the shadow.

Using it in React and Tailwind

Container queries are plain CSS, so they work in any component. Tailwind CSS 4 supports them out of the box:

1export function ProductCard({ product }: { product: Product }) {
2  return (
3    <div className="@container">
4      <article className="grid gap-4 @md:grid-cols-[160px_1fr]">
5        <img src={product.image} alt="" />
6        <div>
7          <h2 className="text-lg @lg:text-2xl">{product.name}</h2>
8        </div>
9      </article>
10    </div>
11  );
12}

Practical advice

• Use media queries for page-level layout and container queries for reusable components.
• A container cannot query itself, so the styled element must be a descendant of the container.
• Name containers when you nest them, so queries target the one you mean.

Sources and further reading

• MDN: CSS container queries