CSS Container Queries

CSS Container Queries

Overview

Container Queries allow components to adapt their styling based on the size of their containing element rather than the viewport. This enables truly reusable, context-aware components that respond to their available space.

When to Use

• Building reusable components that work in different layout contexts
• Card components that adapt between sidebar and main content
• Design systems where components must be layout-agnostic
• Replacing JavaScript-based resize observers for responsive components

Core Patterns

Basic Container Query

/* Define a containment context */
.card-container {
  container-type: inline-size;
  container-name: card;
}

/* Query the container's size */
@container card (min-width: 400px) {
  .card {
    display: grid;
    grid-template-columns: 200px 1fr;
    gap: 1rem;
  }
}

@container card (max-width: 399px) {
  .card {
    display: flex;
    flex-direction: column;
  }
}

Container Query Units

/* cqw = 1% of container width */
/* cqh = 1% of container height */
/* cqi = 1% of container inline size */
/* cqb = 1% of container block size */
/* cqmin = min(cqi, cqb) */
/* cqmax = max(cqi, cqb) */

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

.card-image {
  height: 40cqb;
}

Style Queries (Experimental)

/* Query custom property values */
@container style(--theme: dark) {
  .card {
    background: #1a1a2e;
    color: #eee;
  }
}

@container style(--variant: compact) {
  .card {
    padding: 0.5rem;
  }
}

Nested Containers

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

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

@container sidebar (max-width: 300px) {
  .sidebar-nav { flex-direction: column; }
}

@container widget (min-width: 200px) {
  .widget-content { display: grid; grid-template-columns: 1fr 1fr; }
}

Tailwind CSS v4 Integration

<!-- Tailwind v4 has native container query support -->
<div class="@container">
  <div class="flex flex-col @sm:flex-row @md:grid @md:grid-cols-3">
    <p class="text-sm @lg:text-base">Responsive to container</p>
  </div>
</div>

Guidelines

1. Use container-type: inline-size for most use cases (width-based queries)
2. Name your containers with container-name for clarity in nested contexts
3. Use container query units (cqi, cqw) for fluid typography and spacing
4. Combine with @media — use container queries for components, media queries for layout
5. Progressive enhancement — provide reasonable defaults for non-supporting browsers

Anti-Patterns

• ❌ Using container-type: size when only inline-size is needed (causes unnecessary layout containment)
• ❌ Nesting containers without naming them (ambiguous query targets)
• ❌ Replacing all media queries with container queries (they serve different purposes)
• ❌ Forgetting that container-type creates a new stacking context