CSS Container Queries: The Complete Guide

For years, we built responsive websites using viewport-based media queries. We’d check the screen width and adjust our layouts accordingly. But here’s the problem: a card component doesn’t know if it’s displayed in a sidebar or in the main content area. Container queries change everything.

My Experience

I first encountered container queries while working on a massive design system project. We had dozens of components—cards, sidebars, modals—and each needed to adapt to different contexts. Our solution was a tangled mess of props and CSS classes: Card size="small", Card size="large", Card layout="sidebar".

Then container queries landed in Chrome, and I spent a weekend rebuilding our card component. The result was a single component that automatically adapted to its container. No props. No JavaScript. Just pure CSS.

That moment changed how I think about responsive design entirely.

Understanding Container Queries

Container queries let you style an element based on its parent’s size, not the viewport. Here’s how to use them:

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

/* Then, query the container */
@container card (min-width: 400px) {
  .card {
    display: grid;
    grid-template-columns: 150px 1fr;
  }
}

Container Types Explained

Type	What It Measures	Use Case
inline-size	Width only	Most components
size	Width and height	Complex layouts
normal	No containment	Default behavior

Container Style Queries (New in 2025)

Style queries let you respond to computed style changes:

/* Query custom property values */
@container style(--variant: primary) {
  .button {
    background: blue;
    color: white;
  }
}

Practical Card Component Example

Here’s a real-world card component that adapts beautifully:

/* Define the container */
.product-card-wrapper {
  container-type: inline-size;
  container-name: product;
}

/* Default: Mobile-first styles */
.product-card {
  display: flex;
  flex-direction: column;
  padding: 1rem;
}

.product-card__image {
  width: 100%;
  height: 200px;
  object-fit: cover;
}

/* At 300px: Side-by-side layout */
@container product (min-width: 300px) {
  .product-card {
    flex-direction: row;
    gap: 1rem;
  }

  .product-card__image {
    width: 120px;
    height: auto;
  }
}

/* At 500px: Full feature card */
@container product (min-width: 500px) {
  .product-card {
    flex-direction: column;
    gap: 1.5rem;
  }

  .product-card__image {
    width: 100%;
    height: 250px;
  }

  .product-card__actions {
    display: flex;
    gap: 0.5rem;
  }
}

Combining Container Queries with Media Queries

The power duo: use both for complete responsiveness:

/* Mobile-first base styles */
.navigation {
  display: flex;
  flex-direction: column;
}

/* When there's room in the viewport */
@media (min-width: 768px) {
  .navigation {
    flex-direction: row;
    justify-content: space-between;
  }
}

/* But also adapt to container size */
@container sidebar (max-width: 200px) {
  .navigation {
    flex-direction: column;
    align-items: center;
  }

  .navigation__item {
    padding: 0.25rem;
  }
}

When to Use Container Queries

Use Container Queries When:

• Building reusable components
• Components appear in multiple contexts (sidebar, main content, grid)
• You want self-contained responsive behavior

Stick with Media Queries When:

• Overall page layout changes
• Navigation behavior based on device
• Hiding/showing elements based on viewport

Browser Support Check

As of 2025, container queries have excellent support:

• Chrome/Edge: Full support (since version 105)
• Firefox: Full support (since version 110)
• Safari: Full support (since version 16)
• Can use @supports for fallbacks

@supports not (container-type: inline-size) {
  /* Fallback styles for older browsers */
  .card {
    /* Traditional responsive styles */
  }
}

What Students Should Do Next

1. Convert one component to use container queries — Start with a card or article component
2. Experiment with container-type: inline-size — Understand the performance implications
3. Combine with CSS Grid and Flexbox — Container queries work best with modern layout systems

Container queries represent the future of responsive design. They’re not just a nice-to-have—they’re essential for building truly component-driven design systems.