Container Queries With Tailwind CSS — Setup and Patterns

Container Queries in Tailwind, End to End

Tailwind CSS supports container queries first-class: in v3.2+ via the built-in @container variant and in v4 with a streamlined arbitrary-value syntax. This guide covers both.

Tailwind v3.2+ Setup

Container query support is built in — no plugin needed.

<div class="@container">
  <article class="flex flex-col @md:flex-row @md:gap-4">
    <img src="/cover.jpg" class="@md:w-48" alt="" />
    <div class="@md:flex-1">
      <h3 class="text-base @md:text-lg">Title</h3>
      <p class="text-sm text-muted-foreground">…</p>
    </div>
  </article>
</div>

Default Breakpoints

Class	Width
@xs:	20rem (320px)
@sm:	24rem (384px)
@md:	28rem (448px)
@lg:	32rem (512px)
@xl:	36rem (576px)
@2xl:	42rem (672px)

These are smaller than viewport breakpoints because containers are typically narrower than viewports.

Named Containers

<div class="@container/sidebar">
  <nav class="hidden @md/sidebar:flex flex-col gap-2">
    <a href="/">Home</a>
    <a href="/docs">Docs</a>
  </nav>
</div>

The /sidebar suffix names the container. The variant @md/sidebar: only fires when the sidebar container crosses 28rem — independent of any other container.

Custom Breakpoints (v3)

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      containers: {
        'card': '20rem',     // 320px
        'panel': '37.5rem',  // 600px
      },
    },
  },
};

Use as @card:flex-row or @panel/sidebar:grid.

Tailwind v4 Arbitrary Sizes

<div class="@container">
  <div class="grid grid-cols-1 @min-[400px]:grid-cols-2 @min-[700px]:grid-cols-3">
    …
  </div>
</div>

@min-[400px]: is the inline equivalent of @container (min-width: 400px). No config required.

Common Mistake: Forgetting @container

<!-- BROKEN — no parent declares container-type -->
<div>
  <div class="flex flex-col @md:flex-row">…</div>
</div>

The @md: variant silently fails. Always make sure an ancestor has the @container class (or a custom container declared in CSS).

Hybrid: Viewport + Container

<div class="@container md:flex md:gap-6">
  <aside class="@md:hidden md:block w-64">…</aside>
  <main class="flex-1">
    <div class="grid @md:grid-cols-2">…</div>
  </main>
</div>

md: (no @) targets the viewport; @md: (with @) targets the container. Use both freely.