Container Queries

Container queries let you style descendants based on the size of a parent container rather than the viewport. This makes components truly context-agnostic — they adapt to the space they're given, not to the overall screen.

Browser support: Widely available Baseline since August 2025 (Chrome 105+, Edge 105+, Firefox 110+, Safari 16+). Became Newly available in February 2023 when Firefox 110 shipped support last.

Use cases

• Reusable card/widget components that adapt to their layout context
• Sidebar vs. main content layouts where the same component renders differently
• Design systems and component libraries that must work in varying column widths
• Dashboard widgets and grid items

How it works

You define a containment context on a parent element, then query that container's dimensions from its descendants using the @container at-rule.

Key properties:

• container-type — declares the element as a query container (inline-size or size)
• container-name — gives the container an optional name for targeted queries
• container — shorthand combining name and type (e.g. container: sidebar / inline-size)

.card-wrapper {
  container-type: inline-size;
  container-name: card;
}

@container card (min-width: 400px) {
  .card {
    flex-direction: row;
    gap: 1.5rem;
  }
}

tip

Use named containers (container-name) in complex layouts to avoid ambiguity when multiple ancestor containers are defined.

Container query length units

Unit	Relative to	Description
cqw	Container width	1% of container's width
cqh	Container height	1% of container's height
cqi	Container inline size	1% of container's inline axis
cqb	Container block size	1% of container's block axis
cqmin	Smaller of cqi/cqb	1% of the smaller dimension
cqmax	Larger of cqi/cqb	1% of the larger dimension

These units are useful for fluid sizing that scales with the container:

.card-title {
  font-size: clamp(1rem, 3cqi, 1.75rem);
}

Comparison with media queries

Feature	Media Queries	Container Queries
Responds to	Viewport dimensions	Nearest container ancestor's dimensions
Scope	Page-level	Component-level
Reusability	Component must know its page context	Component is context-agnostic
Best for	Page layout breakpoints	Adaptive, reusable components

Using with Tailwind CSS

Tailwind v4 (native)

Tailwind v4 supports container queries out of the box — no plugin needed.

Mark a container with the @container class (or @container/name for named containers), then use size-variant prefixes on descendants:

Prefix	Min-width
@3xs	16rem
@xs	20rem
@sm	24rem
@md	28rem
@lg	32rem
@xl	36rem
@2xl	42rem
@4xl	56rem
@7xl	80rem

See the Tailwind container queries docs for the full list of breakpoints.

<div class="@container">
  <div class="flex flex-col @md:flex-row gap-4">
    <img src="/thumbnail.jpg" class="w-full @md:w-48" />
    <div>
      <h2 class="text-lg @lg:text-xl">Card title</h2>
      <p>Card description…</p>
    </div>
  </div>
</div>

Tailwind v3 (plugin)

Tailwind v3 requires the @tailwindcss/container-queries plugin.

npm install -D @tailwindcss/container-queries

tailwind.config.js

module.exports = {
  plugins: [require("@tailwindcss/container-queries")],
};

Once installed the class API is the same as v4.

note

For more on our Tailwind CSS setup, see Tailwind CSS.

Gotchas

• Size containment required — The container must have a determinable inline-size. Place it inside a flex/grid context or give it an explicit width; otherwise it may collapse to zero.
• Descendants only — You cannot query and style the container element itself; only its descendants respond to @container rules.
• Style queries are limited — Container style queries (@container style(--theme: dark)) are supported in Chrome/Edge 111+, Safari 18+, and Firefox 151+. Not yet Widely available Baseline.

caution

Prefer inline-size — container-type: size requires containment on both axes, which breaks normal block-axis sizing (height depends on content). Use inline-size unless you have a fixed-height container.

When to use

Use container queries when building reusable components that must adapt to available space regardless of viewport size — component libraries, dashboard widgets, CMS content regions. For page-level layout shifts that depend on the full viewport, media queries remain the right tool.

For a deeper dive with visual examples, see Ahmad Shadeed's container query guide.