CSS Container Queries (@container) Complete Guide

For over a decade, responsive design relied exclusively on viewport media queries. However, modern web applications are assembled from modular components (cards, profile badges, chat widgets). A card component placed inside a narrow sidebar needs a stacked layout, while the exact same card placed in the wide main feed needs a horizontal layout. CSS Container Queries (@container) solve this permanently.

How Container Queries Operate

To use container queries, you must first register a parent element as a containment boundary using container-type:

/* 1. Register the parent element as a Query Container */
.card-wrapper {
  container-type: inline-size;  /* Query container width */
  container-name: cardContainer;/* Optional semantic name */
}

/* 2. Default Base Layout (Vertical Stack for narrow spaces) */
.product-card {
  display: flex;
  flex-direction: column;
  gap: 12px;
}

/* 3. When the CONTAINER is >= 450px wide (NOT viewport!) */
@container (min-width: 450px) {
  .product-card {
    flex-direction: row;         /* Automatically switches to side-by-side! */
    align-items: center;
  }
}

Container Query Units (cqw, cqh)

Container queries also unlock dedicated sizing units relative to the container itself:

• 1cqw: 1% of the query container's width.

• 1cqh: 1% of the query container's height.

.card-title {
  /* Font size scales directly with card size, anywhere on the page! */
  font-size: clamp(1rem, 5cqw, 2rem);
}

Explore Related CSS Tutorials & Next Steps

Boost your CSS and front-end development proficiency by exploring these closely connected topics:

CSS Box Model & border-box

Understand margins, borders, padding, content and the universal box-sizing fix.

CSS Flexbox Complete Guide

Master 1D alignment, justify-content, align-items, flex-wrap and responsive flow.

CSS Grid 2D Layout Matrix

Build powerful two-dimensional grid layouts with template areas and fr units.

CSS Specificity & Cascade

Eliminate styling conflicts and master selector weights from 0,0,0,1 to !important.

Frequently Asked Questions (FAQ) - Student & Interview Review

Q1. What is the difference between container-type: inline-size and size?

'inline-size' enables queries based on container width (horizontal dimension). 'size' enables queries on both width and height, but requires the container to have an explicit height.

Q2. Can an element query itself?

No! An element can only query ancestor containers, not its own dimensions. This prevents infinite layout recalculation loops.

Q3. Do all major browsers support Container Queries in 2026?

Yes! Container queries are supported across all modern browser engines (Chrome, Edge, Safari, Firefox) since early 2023.

Q4. What are Named Container Queries?

Using 'container-name: sidebar' allows you to query a specific ancestor: '@container sidebar (min-width: 300px)', ignoring other intermediate containers.