klen/css-container-queries

CSS Container Queries

A guide for implementing container-based responsive design using CSS container queries and Tailwind CSS.

What

What are Container Queries?

Container queries enable styling elements based on their container's size rather than the viewport size. Unlike media queries that respond to the browser window, container queries make components self-contained and truly reusable.

Key Concept:

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

/* Query the container */
@container card (min-width: 400px) {
  .card-title {
    font-size: 2rem;
  }
}

Tailwind Approach:

<!-- Define a container -->
<div class="@container">
  <!-- Query the container -->
  <div class="@lg:grid-cols-2">
    <!-- Content adapts to container, not viewport -->
  </div>
</div>

Container Query vs Media Query

| Feature | Media Query | Container Query | |---------|-------------|-----------------| | Responds to | Viewport size | Container size | | Reusability | Layout-dependent | Fully portable | | Use case | Page layouts | Component styling | | Syntax | @media | @container |

---

Why

💡 Why Use Container Queries?

1. Component Portability

• Components adapt to their context, not the viewport
• Same component works in sidebar (narrow) or main area (wide)
• No need for different component variants

2. Simpler Component Logic

• Components don't need to know about page layout
• Follows single responsibility principle
• Reduces coupling between components and layouts

3. Better for Design Systems

• Components are truly self-contained
• Works in any layout context (grid, flex, sidebar)
• Easier to maintain and test in isolation

4. Modern Web Architecture

• Aligns with component-based frameworks (React, Vue, Svelte)
• Better for micro-frontends
• More predictable behavior

When to Use Container Queries vs Media Queries

🤔 Use Container Queries when:

• Styling reusable components (cards, widgets, forms)
• Component appears in multiple contexts
• Component needs to adapt to its parent's size
• Building a component library

🤔 Use Media Queries when:

• Changing overall page layout
• Adjusting navigation structure
• Modifying font sizes globally
• Viewport-specific features (like mobile-first approach)

---

Requirements

What to Do

Review and refactor responsive components to use container queries where appropriate.

Implementation Checklist

1. CSS Implementation

Step 1: Define the container

.component-wrapper {
  container-type: inline-size; /* or 'size' for both dimensions */
  container-name: myComponent; /* optional but recommended */
}

Step 2: Add container queries

/* Use the container name */
@container myComponent (min-width: 400px) {
  .component-title {
    font-size: 2rem;
  }
}

/* Or query nearest container */
@container (min-width: 400px) {
  .component-title {
    font-size: 2rem;
  }
}

Step 3: Use modern range syntax (optional)

@container (400px <= width <= 800px) {
  .component-content {
    display: grid;
    grid-template-columns: repeat(2, 1fr);
  }
}

3. Tailwind CSS Implementation

Step 1: Define container with @container class

<div class="@container">
  <!-- This is now a container context -->
</div>

Step 2: Use container query variants

<div class="@container">
  <div class="grid @lg:grid-cols-2 @xl:grid-cols-3">
    <!-- Responds to container size, not viewport -->
  </div>
</div>

Available Tailwind Container Breakpoints:

• @3xs - @container (width >= 16rem) (256px)
• @2xs - @container (width >= 18rem) (288px)
• @xs - @container (width >= 20rem) (320px)
• @sm - @container (width >= 24rem) (384px)
• @md - @container (width >= 28rem) (448px)
• @lg - @container (width >= 32rem) (512px)
• @xl - @container (width >= 36rem) (576px)
• @2xl - @container (width >= 42rem) (672px)
• @3xl - @container (width >= 48rem) (768px)
• @4xl - @container (width >= 56rem) (896px)
• @5xl - @container (width >= 64rem) (1024px)
• @6xl - @container (width >= 72rem) (1152px)
• @7xl - @container (width >= 80rem) (1280px)

📝 Note: These are Tailwind's default breakpoints. You can customize them in globals.css (Tailwind v4) using CSS variables or use arbitrary values like @min-[500px]:grid for custom container widths.

Step 3: Named containers (Tailwind)

<!-- Define named container -->
<div class="@container/main">
  <!-- Query specific container -->
  <div class="@lg/main:grid-cols-3">
    <!-- Content -->
  </div>
</div>

4. Common Patterns

Pattern 1: Card Component

<!-- Tailwind -->
<div class="@container">
  <article class="@lg:flex @lg:gap-4">
    <img class="@lg:w-48" src="..." alt="..." />
    <div class="@lg:flex-1">
      <h2 class="text-xl @lg:text-2xl">Title</h2>
      <p class="@lg:text-base">Description</p>
    </div>
  </article>
</div>

Pattern 2: Responsive Grid

<!-- Tailwind -->
<div class="@container">
  <div class="grid @sm:grid-cols-2 @lg:grid-cols-3 @2xl:grid-cols-4 gap-4">
    <!-- Items adapt to container width -->
  </div>
</div>

Pattern 3: Mixed Container + Media Queries

<!-- Use media queries for layout, container queries for components -->
<main class="max-w-7xl mx-auto md:grid md:grid-cols-3">
  <!-- Sidebar: narrow container -->
  <aside class="md:col-span-1">
    <div class="@container">
      <div class="@lg:hidden">Compact view</div>
    </div>
  </aside>

  <!-- Main: wide container -->
  <div class="md:col-span-2">
    <div class="@container">
      <div class="@2xl:grid-cols-3">Full width view</div>
    </div>
  </div>
</main>

5. Review Process

✅ Focus on:

• Recently modified components
• Components using media queries for internal layout
• Reusable component patterns

⚠️ Watch out for:

• Overusing container queries (media queries are still needed for layouts)
• Nesting too many containers (can cause confusion)
• Not naming containers when multiple are present
• Fixed heights (let content flow naturally)

❌ Avoid:

• Replacing all media queries with container queries
• Container queries for page-level layouts
• Complex nesting without clear container names

6. Testing Checklist

After implementing container queries:

• [ ] Component works in narrow containers (sidebar)
• [ ] Component works in wide containers (main content)
• [ ] Component works in medium containers (grid cells)
• [ ] No layout breaks at container breakpoints
• [ ] Content doesn't overflow fixed heights
• [ ] Performance is acceptable (container queries are efficient)

7. Browser Support

✅ Supported:

• Chrome 106+
• Edge 106+
• Safari 16+
• Firefox 110+

💡 Tip: For older browsers, use @supports or progressive enhancement:

/* Fallback for older browsers */
.component {
  padding: 1rem;
}

/* Enhanced with container queries */
@supports (container-type: inline-size) {
  @container (min-width: 400px) {
    .component {
      padding: 2rem;
    }
  }
}

---

Examples

✅ Good: Component-Based Container Query

<!-- Tailwind: Reusable card adapts to any container -->
<div class="@container">
  <article class="p-4 @md:p-6 @lg:flex @lg:gap-6">
    <img class="w-full @lg:w-64 rounded" src="card.jpg" alt="" />
    <div>
      <h2 class="text-lg @md:text-xl @lg:text-2xl font-bold">
        Card Title
      </h2>
      <p class="text-sm @md:text-base @lg:text-lg">
        Card description that adapts to container width.
      </p>
      <button class="mt-4 @md:mt-6">Action</button>
    </div>
  </article>
</div>

Why it's good: Card is self-contained and works in any layout context.

❌ Bad: Using Media Queries for Component Internals

<!-- Tailwind: Component depends on viewport, not container -->
<article class="p-4 md:p-6 lg:flex lg:gap-6">
  <img class="w-full lg:w-64 rounded" src="card.jpg" alt="" />
  <div>
    <h2 class="text-lg md:text-xl lg:text-2xl font-bold">
      Card Title
    </h2>
  </div>
</article>

Why it's bad: Card assumes it's always full width at md breakpoint. Breaks when placed in a sidebar.

✅ Good: Named Containers for Clarity

<!-- Tailwind: Multiple containers with clear names -->
<div class="@container/sidebar">
  <nav class="@lg/sidebar:grid-cols-1">
    <!-- Sidebar navigation -->
  </nav>
</div>

<div class="@container/main">
  <div class="@lg/main:grid-cols-3">
    <!-- Main content grid -->
  </div>
</div>

Why it's good: Clear which container each query refers to.

---

Common Mistakes

❌ Mistake 1: Using container queries for page layouts

<!-- Don't do this -->
<body class="@container">
  <main class="@lg:grid @lg:grid-cols-3">

Fix: Use media queries for page-level layouts.

❌ Mistake 2: Forgetting to define the container

<!-- Don't do this -->
<div>
  <div class="@lg:grid-cols-2"><!-- Won't work! --></div>
</div>

Fix: Always add @container to the parent.

❌ Mistake 3: Fixed heights with responsive content

/* Don't do this */
.container {
  height: 400px; /* Fixed height */
}

@container (min-width: 600px) {
  .content {
    columns: 2; /* Text will overflow! */
  }
}

Fix: Use min-height or let content determine height.

❌ Mistake 4: Too many nested containers

<!-- Don't do this -->
<div class="@container">
  <div class="@container">
    <div class="@container">
      <div class="@lg:..."><!-- Confusing! --></div>
    </div>
  </div>
</div>

Fix: Use named containers and keep nesting shallow.

---

Quick Reference

Vanilla CSS

/* Define container */
.wrapper {
  container-type: inline-size; /* or 'size' */
  container-name: myContainer; /* optional */
}

/* Query container */
@container myContainer (min-width: 400px) {
  /* styles */
}

/* Modern range syntax */
@container (400px <= width <= 800px) {
  /* styles */
}

Tailwind CSS

<!-- Define container -->
<div class="@container">
  <!-- Use container variants -->
  <div class="@sm:text-lg @md:grid-cols-2">
</div>

<!-- Named container -->
<div class="@container/name">
  <div class="@lg/name:grid-cols-3">
</div>

---

Resources

• MDN: CSS Container Queries
• Tailwind: Container Queries
• CSS Tricks: Container Queries Guide
• Can I Use: Container Queries