Why CSS Container Queries Are Better Than Media Queries for Component-Based Design (And When They're Not)

For decades, media queries have been the foundation of responsive web design. But they share a fundamental limitation that becomes painfully obvious when you’re building modern component libraries and design systems: media queries respond to the viewport, not to the actual space a component occupies. You’ve likely encountered this frustration—a card component that looks perfect at 1200px breaks when placed in a sidebar at 768px. CSS container queries solve this exact problem by letting components respond to their container’s dimensions rather than the browser window. But this powerful tool isn’t a silver bullet, and understanding when to use each approach is critical for building scalable, performant design systems.

The Core Problem: Viewport-Based vs. Container-Based Thinking

Media queries bind component behavior to global viewport dimensions. This architectural mismatch creates cascading complexity in component libraries. When you’re designing a responsive button, card, or grid component, you’re not thinking about the user’s screen size—you’re thinking about how much space your component actually has available.

Consider a real scenario: you’ve built a product card component that looks great at desktop sizes (1200px+). At 768px, the layout compresses nicely. But when that same card is placed inside a sidebar container that’s only 300px wide, your media queries still think you’re at tablet size and apply tablet styles that overflow the sidebar. Now you’re forced to add context-specific variants, use JavaScript to track container widths, or refactor the component entirely.

CSS container queries eliminate this friction by making components genuinely self-aware. A component only needs to know about its own container size, not about the global viewport. This is architecturally superior for component libraries where the same component might live in completely different layout contexts.

How CSS Container Queries Work: The Technical Foundation

Container queries require two key pieces: a container context and query syntax.

Define a container: Use the container-type property on a parent element to establish a query context.
Query the container: Use @container at-rules to apply styles based on the container’s dimensions.
Scope the context: Optionally use container-name to target specific containers when nesting is complex.

Here’s the baseline syntax:

/* Define a container context */
.card-container {
  container-type: inline-size; /* responds to width changes */
  width: 100%;
}

/* Query that container */
@container (min-width: 400px) {
  .card {
    display: grid;
    grid-template-columns: 1fr 1fr;
  }
}

@container (min-width: 600px) {
  .card {
    padding: 2rem;
  }
}

The container-type: inline-size property is crucial—it tells the browser to track width changes on that element. (You can also use size to track both width and height, though this carries slight performance overhead.)

Practical Example 1: Building a Responsive Card Component

Let’s build a product card that adapts purely based on its container width, not the viewport:

<!-- HTML structure -->
<div class="card-wrapper">
  <article class="product-card">
    <img src="product.jpg" alt="Product" />
    <h3>Product Name</h3>
    <p class="description">Product description goes here</p>
    <span class="price">$99.99</span>
    <button>Add to Cart</button>
  </article>
</div>

<style>
/* Establish container context */
.card-wrapper {
  container-type: inline-size;
  width: 100%;
}

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

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

.description {
  font-size: 0.875rem;
  color: #666;
  display: none; /* hidden on small containers */
}

.price {
  font-weight: bold;
  font-size: 1.25rem;
}

button {
  padding: 0.5rem;
  font-size: 0.875rem;
}

/* Medium containers: 350px+ */
@container (min-width: 350px) {
  .description {
    display: block; /* show description */
  }
  
  button {
    padding: 0.75rem 1rem;
    font-size: 1rem;
  }
}

/* Large containers: 500px+ */
@container (min-width: 500px) {
  .product-card {
    flex-direction: row;
    gap: 1.5rem;
  }
  
  .product-card img {
    width: 200px;
    height: 200px;
    flex-shrink: 0;
  }
  
  .product-card > div {
    flex: 1;
    display: flex;
    flex-direction: column;
    justify-content: space-between;
  }
}
</style>

This single card component now works perfectly in a 300px sidebar, a 600px grid column, or a full-width 1200px layout—all without JavaScript or media queries. The component scales based on its actual available space.

Practical Example 2: Named Containers in Complex Layouts

When nesting containers, named containers prevent ambiguity about which container context you’re querying:

/* Parent containers with specific names */
.sidebar {
  container-type: inline-size;
  container-name: sidebar;
  width: 100%;
}

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

/* Components can query their specific container */
.card {
  padding: 1rem;
}

/* When inside sidebar, keep it compact */
@container sidebar (min-width: 250px) {
  .card {
    padding: 0.75rem;
  }
  
  .card-title {
    font-size: 1rem;
  }
}

/* When inside main content, use more spacious layout */
@container main (min-width: 600px) {
  .card {
    padding: 2rem;
    display: grid;
    grid-template-columns: 200px 1fr;
    gap: 1.5rem;
  }
  
  .card-title {
    font-size: 1.5rem;
  }
}

/* Can also query by height */
@container main (min-height: 800px) {
  .card {
    min-height: 300px;
  }
}

This approach scales beautifully in design systems where the same component needs dramatically different layouts depending on its context.

Container Queries vs. Media Queries: When Each Excels

Use Container Queries When:

Building reusable components that live in multiple layout contexts (sidebar, main content, modal, etc.)
Creating design systems where components need self-contained responsive logic
Developing flexible grid layouts where column widths vary based on parent containers
Implementing dashboard layouts with resizable or rearrangeable sections
Reducing stylesheet complexity by avoiding context-specific component variants

Stick With Media Queries When:

Designing page-level layouts (header, footer, navigation) that genuinely respond to viewport width
Supporting older browsers (Chrome 105+, Safari 16+, Firefox 110+; IE and older versions lack support)
Building simple, non-nested layouts where a single breakpoint strategy suffices
Targeting performance-critical scenarios on very low-end devices (though the difference is minimal)
Designing experiences that need viewport-aware logic (showing/hiding a hamburger menu based on screen size)

Performance Implications: Real-World Metrics

A common concern is whether container queries carry performance overhead compared to media queries. Testing shows the difference is negligible for most applications:

Paint and Layout Performance: Container queries and media queries have virtually identical performance characteristics. Both trigger repaints only when their conditions change. A Chromium benchmark (2023) found less than 1ms difference between media query and container query recalculation in typical scenarios.

CSS File Size: Container queries can actually reduce total CSS by eliminating context-specific component variants. A design system that previously had `.card`, `.card–sidebar`, and `.card–modal` variants can now use a single `.card` component querying multiple container contexts. This typically reduces CSS by 10-15% in component-heavy codebases.

JavaScript Impact: Container queries eliminate the need for ResizeObserver patterns or manual dimension tracking, removing JavaScript overhead entirely from responsive logic. That’s a genuine win for performance-conscious teams.

Browser Support Considerations: As of 2024, container queries are supported in all modern browsers (Chrome 105+, Safari 16+, Firefox 110+, Edge 105+). Approximately 85% of global traffic reaches browsers with full support. For projects requiring older browser support, progressive enhancement strategies (media queries as fallback) work well.

Browser Support Strategy and Progressive Enhancement

You don’t have to choose between container queries and media queries. A pragmatic approach uses both:

Lead with container queries: Write your primary responsive logic using @container for component-level responsiveness.
Add media query fallbacks: Include media queries for page-level layouts and as safety nets for older browsers.
Test older browsers: Use feature detection to ensure degradation is acceptable (components will use media query styles on unsupported browsers).
Document support requirements: Make clear in your design system documentation which browsers get container query enhancements.

Modern design systems increasingly take this hybrid approach, recognizing that container queries excel at component logic while media queries remain essential for page-level adaptation.

Common Pitfalls and How to Avoid Them

Pitfall 1: Creating Too Many Breakpoints

The granularity of container queries makes it tempting to define dozens of breakpoints. Resist this. Limit yourself to 3-5 container query breakpoints per component (typically: 250px, 400px, 600px, 800px). This maintains maintainability while capturing the essential responsive behaviors.

Pitfall 2: Forgetting container-type Declarations

A common mistake is writing @container rules without establishing a container context on a parent. The container queries simply won’t trigger. Always verify that container-type: inline-size (or size) is set on a parent element before querying it.

Pitfall 3: Nesting Container Contexts Unnecessarily

Each container-type declaration adds a small computational cost. Don’t nest containers unless you actually need different query contexts. A single container context wrapping your entire component library section is usually sufficient.

Pitfall 4: Relying on Container Queries for Viewport-Specific Logic

Container queries can’t replace media queries for viewport-wide decisions (like showing/hiding a mobile menu). If you need to know the actual viewport width, media queries are the correct tool.

Building a Design System With Container Queries: Step-by-Step

Audit your components: List all components that currently have context-specific variants (e.g., card, button, grid). These are candidates for container query conversion.
Define container breakpoints: Choose 3-5 width breakpoints that represent meaningful layout changes. (250px, 400px, 600px usually covers 90% of scenarios.)
Create container wrapper components: For each component that needs responsive behavior, add a wrapper with container-type: inline-size.
Refactor component styles: Move context-specific styles into @container rules. Delete variant classes.
Test across contexts: Place each component in narrow sidebars, grid columns, full-width sections, and modal dialogs. Verify behavior matches expectations.
Document in Storybook: Create stories showing components at different container widths using viewport controls.
Add fallbacks: Include media query fallbacks for older browser support if your project requires it.

Key Takeaways for Implementation

CSS container queries represent a fundamental shift in how we think about responsive component design. Rather than forcing components to adapt to a global viewport dimension, container queries let components adapt to their actual allocated space. This is architecturally superior for modern component libraries and design systems.

Start by migrating highly-reused components (cards, buttons, grid items) to container queries. These components exist in multiple layout contexts and benefit most from self-contained responsive logic. Avoid overcomplicating by adding too many breakpoints—three to five per component is the practical limit.

Remember that container queries complement rather than replace media queries. Page-level layouts, viewport-aware navigation, and older browser support still require media queries. A mature design system uses both tools strategically: media queries for page-level adaptation, container queries for component-level responsiveness.

For technical founders rebuilding legacy codebases, migrating to container queries for component-heavy projects can reduce CSS complexity by 15-20% and eliminate entire classes of JavaScript dimension-tracking code. The investment in refactoring pays dividends in maintainability and developer experience.

Test your container query implementations thoroughly across real container widths, not just viewport widths. Use browser DevTools to inspect computed styles at different container dimensions. Document your container breakpoint strategy in your design system documentation so team members understand when and why each breakpoint exists.