Skip to main content
HTML5ANDCSS3 logoHTML5ANDCSS3Tools and Tutorials

CSS Responsive Design

Container Queries

Written by Published

Adapt a component to the space provided by its container instead of the size of the viewport. You will establish named query containers, write size and style queries, use container-relative units, and decide when media queries remain appropriate.

Container queries condition a component’s styles on an ancestor container rather than on the viewport. The component can therefore adapt to the space it actually receives.

A card may appear in a wide main column, a narrow sidebar, or a dashboard cell while the viewport remains unchanged. Viewport breakpoints cannot describe those situations reliably. By establishing an inline-size query container, the card can switch layout at the point where its own content and available width require it. This topic also connects with CSS Media Queries and Feature Queries.

Establish a query container

Example

css

.card-region {
  container: cards / inline-size;
}

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

@container cards (width >= 34rem) {
  .card {
    grid-template-columns: 10rem 1fr;
  }
}

Size queries require containment on the queried axis. Naming the container prevents an inner component from accidentally querying the wrong ancestor.

Container query units

Example

css

.card__title {
  font-size: clamp(1.2rem, 4cqi, 2rem);
}

cqi is one percent of the query container’s inline size. Other units include cqw, cqh, cqb, cqmin, and cqmax.

Style queries

Example

css

@container style(--featured: true) {
  .card { border-color: gold; }
}

Query a container's scroll state

Scroll-state queries can respond when a sticky element is stuck, an item is snapped, or a container can still scroll in a direction. Declare a scroll-state query container, then test its state from an @container rule.

Example

css

.section-heading {
  position: sticky;
  inset-block-start: 0;
  container: section-heading / scroll-state;
}

@container section-heading scroll-state(stuck: top) {
  .section-heading__content {
    box-shadow: 0 0.35rem 0.8rem rgb(15 23 42 / 0.18);
  }
}

Container Query Reference

SyntaxPurposeExample
container-typeEstablishes a size query container.container-type: inline-size
container-nameNames a query container.container-name: card
@containerApplies rules according to container conditions.@container card (width > 30rem)
cqwRepresents one percent of the query container's width.font-size: 4cqw
scroll-state()Tests whether a container is stuck, snapped, scrolled, or scrollable.scroll-state(stuck: top)

Complete Example

Run the complete document below in the Try It editor. Resize the preview or interact with the controls where the example calls for it.

Complete runnable example

html

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Container Queries example</title>
  <style>
    * { box-sizing: border-box; }
    body {
      margin: 0;
      padding: 2rem;
      font-family: system-ui, sans-serif;
      line-height: 1.5;
    }
    main { max-width: 70rem; margin-inline: auto; }
    article, section, aside, form, .card, .panel {
      padding: 1rem;
      border: 1px solid #cbd5e1;
      border-radius: 0.6rem;
    }

.card-region {
  container: cards / inline-size;
}

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

@container cards (width >= 34rem) {
  .card {
    grid-template-columns: 10rem 1fr;
  }
}

.card__title {
  font-size: clamp(1.2rem, 4cqi, 2rem);
}

@container style(--featured: true) {
  .card { border-color: gold; }
}

.section-heading {
  position: sticky;
  inset-block-start: 0;
  container: section-heading / scroll-state;
}

@container section-heading scroll-state(stuck: top) {
  .section-heading__content {
    box-shadow: 0 0.35rem 0.8rem rgb(15 23 42 / 0.18);
  }
}
  </style>
</head>
<body>
  <main class="card-region"><article class="card"><div aria-hidden="true">◼</div><section><h1 class="card__title">Container-aware card</h1><p>Resize the preview. The card responds to its container.</p></section></article></main>
</body>
</html>

Browser Support

Feature
Chrome
Edge
Firefox
Safari
@container size queries10510511016
Scroll-state queries133133NoNo

Versions show the first stable desktop release with unprefixed support. Data source: MDN Browser Compatibility Data 8.0.8. A partial-support note is included where it changes how the example behaves.

Notes

  • Use media queries for page- or device-level conditions. Use container queries when the same component can appear in differently sized regions.
  • Scroll-state queries still have limited browser support. Keep the ordinary sticky or snapped presentation complete, and use the query only to add feedback.
  • Test the example with real content, keyboard input, browser zoom, and the narrowest layout your project supports.
  • Use a fallback when the support table shows that one of your required browsers predates the feature.

Conclusion

Container queries make a component respond to the space it actually receives.

Name containers when nesting could make the queried ancestor ambiguous, and keep query thresholds tied to component behavior rather than common device widths. Continue using media queries for page-wide environment conditions such as viewport layout, printing, or user preferences.

PreviousMobile First DesignNextPreference Media Queries