ai CSS: container query 2026-06-06

2026-06-03

xtodo

ai generated

CSS Container Queries let you apply styles to elements based on the size (or other features) of their containing element, rather than the viewport. This makes truly reusable, component-driven responsive design possible.

Unlike media queries (@media), which are global, container queries are local to a specific parent/container.

Why Container Queries Matter

A card component can look different when placed in a narrow sidebar vs. a wide main column.
No more brittle viewport-based breakpoints that break when components are reused.
Enables intrinsic, container-aware layouts.

Browser Support: Baseline (widely available) across Chrome/Edge 105+, Firefox 110+, Safari 16+ (since ~2023). Fully production-ready in 2026.

Core Concepts

Containment Context — You explicitly mark an element as a container using the container-type property.
Container Query — Use the @container at-rule to apply styles when the container meets certain conditions.
Optional Naming — Give containers names with container-name for targeted queries.

Step 1: Define a Container

.card-container {
  container-type: inline-size; /* Most common and performant */
}

/* Or for both width and height (more expensive) */
.full-size-container {
  container-type: size;
}

Values for container-type:

inline-size — Queries only inline direction (usually width). Recommended default.
size — Queries both width and height.
style — For style-based queries (e.g., custom properties) — partial support.
scroll-state — Newer for scroll-related queries.

Step 2: Write a Container Query

@container (min-width: 400px) {
  .card {
    display: flex;
    flex-direction: row;
    gap: 1rem;
  }

  .card img {
    width: 150px;
  }
}

This applies styles to .card (and descendants) when its nearest container with container-type is at least 400px wide.

Example: Responsive Card Component

HTML

<div class="card-container">
  <article class="card">
    <img src="..." alt="">
    <div class="content">
      <h2>Title</h2>
      <p>Description...</p>
    </div>
  </article>
</div>

CSS

.card-container {
  container-type: inline-size;
  container-name: card; /* Optional but useful */
}

.card {
  display: flex;
  flex-direction: column;
  gap: 1rem;
}

/* Narrow card (default) */
@container card (max-width: 350px) {
  .card {
    font-size: 0.9rem;
  }
}

/* Wide card */
@container card (min-width: 400px) {
  .card {
    flex-direction: row;
  }

  .card img {
    flex: 0 0 180px;
  }
}

Naming Containers

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

.main-content {
  container-name: main;
  container-type: inline-size;
}

/* Target specific container */
@container sidebar (max-width: 300px) {
  .widget { /* styles for narrow sidebar */ }
}

@container main (min-width: 800px) {
  .widget { /* styles for wide main area */ }
}

You can combine name + condition or omit the name (uses nearest ancestor container).

Container Query Length Units (cqi, cqmin, etc.)

These are relative to the container:

cqi — 1% of container inline size (width)
cqb — 1% of container block size (height)
cqmin / cqmax — smaller/larger of the two
cqw / cqh — container width/height

Example

@container (min-width: 30rem) {
  h2 {
    font-size: clamp(1.5rem, 5cqi, 3rem);
  }
}

This scales typography beautifully based on the container.

Logical Operators

Just like media queries:

@container (width > 400px) and (height > 500px) { ... }

@container not (max-width: 300px) { ... }

@container (orientation: portrait) { ... }

Style Queries (Advanced)

Query based on computed styles (e.g., custom properties):

.container {
  container-type: style;
  --theme: light;
}

@container style(--theme: dark) {
  .card { background: #333; color: white; }
}

Support is still evolving (stronger in 2026).

Best Practices

Wrap components in dedicated container elements rather than making layout grids themselves containers.
Prefer inline-size unless you truly need vertical queries.
Combine with clamp(), min(), max(), and modern layout (Flex/Grid) for powerful results.
Use meaningful container names in large projects.
Test performance — too many containers can cause extra layout work, but modern browsers handle it well.
Fallbacks: Container queries gracefully degrade; elements just won't respond to container changes if unsupported.

Common Patterns

Responsive Typography

@container (min-width: 20rem) {
  h1 { font-size: 2.5rem; }
}

Component Variants

Horizontal/vertical list layouts
Collapsible sidebars
Dashboard widgets that adapt to panel size

With CSS Nesting (modern browsers)

.card-container {
  container-type: inline-size;

  & .card {
    /* base styles */

    @container (min-width: 500px) {
      /* wide styles */
    }
  }
}

Limitations & Gotchas

You cannot query the element itself if it's the container (avoid circularity).
container-type: size is more expensive than inline-size.
No direct parent querying beyond the containment context.
Style queries have limited support compared to size queries.