CSS Container Queries

Imagine designing a toy cars display box. Standard media queries only check how big the entire living room is to decide where to place the display box. If the box is placed in a small corner or on a massive table, it cannot adapt itself locally. Container queries solve this issue. They allow components to style themselves based on the physical size of their immediate parent container, rather than the global size of the browser window. This means a sidebar card can automatically transform from a compact vertical list into a wide horizontal banner as its parent element expands.

In this page:

The Container Query Concept
Defining an Inline-Size Container
Writing Container Queries
Container Query Units
Named Containers

The Container Query Concept

Historically, responsive design depended on viewport-driven media queries. Container queries shift this responsibility, allowing elements to query the dimensions of their nearest ancestor container styled with a container context.

Note: Use container queries when building highly modular widgets designed to be reused across different page layouts.

Warning: An element cannot query its own container context directly; it can only query its parents.

Example: The Container Query Concept

css

<style>
.ancestor {
  border: 2px dashed #999;
  padding: 16px;
}
.widget {
  border: 2px solid steelblue;
  background: #eef;
  padding: 10px;
}
</style>
<div class="ancestor">
  <div class="widget">
    Widget queries its nearest ancestor's size
  </div>
</div>

Defining an Inline-Size Container

Setting the container-type property to inline-size tells the browser to monitor the width of the parent container, allowing child elements to adapt as the parent changes width.

Note: Use container-type: inline-size for most layouts, as vertical height tracking is rarely required.

Warning: Setting container-type to size can cause infinite loops if child elements change the parent container's height.

Example: Defining an Inline-Size Container

css

<style>
.widget {
  container-type: inline-size;
  border: 2px solid steelblue;
  background: #eef;
  padding: 10px;
}
</style>
<div class="widget">
  <p>Content that can respond to container width</p>
</div>

Writing Container Queries

You write container queries using the @container rule, specifying the minimum or maximum parent container width needed to apply specific styles.

Note: Keep your container query breakpoints focused on the component's design rather than specific device widths.

Warning: Styles declared inside container queries will only run if a parent element has an active container-type defined.

Example: Writing Container Queries

css

<style>
.widget {
  container-type: inline-size;
  border: 2px solid steelblue;
  background: #eef;
  padding: 10px;
}
@container (min-width: 400px) {
  .widget p {
    font-size: 1.5rem;
  }
}
</style>
<div class="widget">
  <p>Text</p>
</div>

Container Query Units

Container queries introduce unique units based on the parent's size: cqw (1% of container width) and cqh (1% of container height), allowing child elements to scale proportionally relative to their parent container.

Note: Use cqw units to scale font sizes dynamically based on the parent container's width.

Warning: Using container query units on containers without size tracking enabled will render them at 0px.

Example: Container Query Units

css

<style>
.widget {
  container-type: inline-size;
  border: 2px solid steelblue;
  background: #eef;
  padding: 10px;
}
.widget p {
  font-size: 10cqw;
}
</style>
<div class="widget">
  <p>Scales with container width</p>
</div>

Named Containers

If an element has multiple parent containers, it will query the nearest one by default. The container-name property allows you to name containers and target queries specifically to that named container.

Note: Use named containers to build complex page layouts with nested, independent component grids.

Warning: Ensure your container-name values are unique to prevent selector conflicts.

Example: Named Containers

css

<style>
.widget {
  container-type: inline-size;
  container-name: sidebar;
  border: 2px solid steelblue;
  background: #eef;
  padding: 10px;
}
@container sidebar (min-width: 300px) {
  .widget p {
    color: blue;
  }
}
</style>
<div class="widget">
  <p>Text</p>
</div>

Common Mistakes

Attempting to query an element's own container size directly inside its own styles.
Forgetting to declare container-type on parent elements, causing container queries to fail.
Omitting standard length units like px or % inside your container query breakpoints.

Chapter Summary

Container queries allow child elements to adapt their layout dynamically based on the width of their parent container.
Initialize container contexts on parent elements using container-type: inline-size.
Write container queries using the @container rule, and use cqw and cqh units for relative container scaling.

Browser Support

CSS container queries are supported natively by all modern web browsers.

🔒

Chapter Quiz — Complete all 25 topics to unlock

0/25 topics done

Complete these topics first:

← Previous Lesson CSS Custom Properties Next Lesson → CSS Subgrid