For years, web developers relied solely on media queries to create responsive layouts — adjusting designs based on the viewport width. But what if your component lives inside a sidebar one moment and a full-width section the next? Media queries can’t help there. Enter CSS Container Queries, now fully supported across all major browsers and rapidly becoming the standard for building truly responsive, context-aware components in 2026.

In this guide, you’ll learn how container queries work, how they differ from media queries, and how to use them with practical, copy-paste-ready code examples.

What Are Container Queries?

Container queries let you style an element based on the size of its parent container, not the browser viewport. This means a card component can adapt its layout whether it’s placed in a narrow sidebar or a wide content area — without any JavaScript.

The key CSS properties involved are:

• container-type — declares an element as a query container
• container-name — optionally names the container for targeted queries
• @container — the at-rule used to write conditional styles

Basic Syntax

First, you define a containment context on a parent element. Then you write @container rules that apply styles based on that container’s dimensions.

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

/* Step 2: Write container query rules */
@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;
  }
}

With this setup, the .card component switches between a horizontal grid layout and a vertical stack purely based on how much space .card-wrapper has — regardless of screen size.

Container Queries vs Media Queries

Here’s a quick comparison to solidify the difference:

Practical Example: Responsive Product Card

Let’s build a real-world product card that adapts to its container. This is the kind of component you’d use in an e-commerce dashboard or a CMS.

<!-- HTML -->
<div class="product-container">
  <div class="product-card">
    <img src="/product.jpg" alt="Product" class="product-img" />
    <div class="product-info">
      <h3>Wireless Headphones</h3>
      <p class="price">$79.99</p>
      <p class="desc">Noise-cancelling, 30hr battery, Bluetooth 5.3</p>
      <button class="buy-btn">Add to Cart</button>
    </div>
  </div>
</div>

/* CSS */
.product-container {
  container-type: inline-size;
  container-name: product;
}

.product-card {
  display: flex;
  flex-direction: column;
  border: 1px solid #e0e0e0;
  border-radius: 12px;
  overflow: hidden;
  background: #fff;
}

.product-img {
  width: 100%;
  aspect-ratio: 16 / 9;
  object-fit: cover;
}

.product-info {
  padding: 1rem;
}

.buy-btn {
  background: #2563eb;
  color: white;
  border: none;
  padding: 0.6rem 1.2rem;
  border-radius: 8px;
  cursor: pointer;
  font-size: 0.95rem;
}

/* When container is wide enough, go horizontal */
@container product (min-width: 500px) {
  .product-card {
    flex-direction: row;
    align-items: center;
  }

  .product-img {
    width: 40%;
    aspect-ratio: 1;
    border-radius: 12px 0 0 12px;
  }

  .product-info {
    flex: 1;
    padding: 1.5rem;
  }
}

/* When container is very wide, add more spacing */
@container product (min-width: 750px) {
  .product-info h3 {
    font-size: 1.5rem;
  }

  .price {
    font-size: 1.3rem;
    font-weight: bold;
    color: #16a34a;
  }
}

Now this single card component renders beautifully whether it’s in a 300px sidebar widget or an 800px main content area. No JavaScript. No media query hacks.

Using Container Query Units

CSS also introduced container query length units that let you size things relative to the container:

• cqi — 1% of the container’s inline size
• cqb — 1% of the container’s block size
• cqw / cqh — container query width/height
• cqmin / cqmax — smaller/larger of cqi and cqb

.product-container {
  container-type: inline-size;
}

.product-info h3 {
  /* Font size scales with container width */
  font-size: clamp(1rem, 4cqi, 2rem);
}

.product-img {
  /* Image height relative to container */
  height: 30cqi;
}

This is incredibly powerful for creating fluid typography and spacing that responds to the component’s actual context.

Nested Containers

You can nest containers and target specific ones by name:

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

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

/* Target the widget container specifically */
@container widget (max-width: 300px) {
  .widget-chart {
    display: none; /* Hide chart in tiny widgets */
  }
}

/* Target the dashboard container */
@container dashboard (min-width: 1200px) {
  .widget {
    min-height: 400px;
  }
}

Style Queries (Bonus: Experimental)

CSS is also gaining style queries — the ability to query a container’s computed style values, not just size. While still experimental in some browsers, here’s the syntax:

.card-wrapper {
  --theme: dark;
}

@container style(--theme: dark) {
  .card {
    background: #1a1a2e;
    color: #eee;
  }
}

This lets components adapt to CSS custom properties set by their ancestors — a huge win for theming systems.

Browser Support and Fallbacks

As of 2026, container queries have full support in Chrome, Firefox, Safari, and Edge. For the rare edge case where you need a fallback:

/* Fallback: always use column layout */
.card {
  display: flex;
  flex-direction: column;
}

/* Enhanced: switch to row when container allows */
@supports (container-type: inline-size) {
  .card-wrapper {
    container-type: inline-size;
  }

  @container (min-width: 500px) {
    .card {
      flex-direction: row;
    }
  }
}

Key Takeaways

• Use container queries when building reusable components that live in different layout contexts
• Keep media queries for page-level layout decisions (navigation, overall grid)
• Name your containers to avoid ambiguity in nested layouts
• Combine with container units (cqi, cqb) for fluid, context-aware sizing
• Progressive enhancement works naturally — old browsers get the default layout

Container queries represent a fundamental shift in how we think about responsive design. Instead of asking “how wide is the screen?”, we now ask “how much space does my component have?” Start using them today — your future self (and your component library) will thank you.