Container Queries in Tailwind CSS

Tired of your website looking like a funhouse mirror on different screen sizes? Ever wished your components could just know how much space they have and adjust themselves accordingly, instead of relying on the whole page’s width? Well, buckle up, buttercup, because container queries are here to make your responsive design dreams a reality!

And guess what? Tailwind CSS v4 is practically throwing a party for them, with native support via the @container utility and super-smart responsive variants. Get ready to build truly modular, layout-aware components that adapt like chameleons. In this post, we’re diving headfirst into Tailwind’s awesome implementation—how to wield its power, when it’s your best friend, and what tiny quirks to keep in mind.

What is `@container` in Tailwind CSS?

Tailwind v4 natively supports container queries—no plugin required. Adding @container to an element applies container-type: inline-size, turning it into a container that its children can respond to based on width, not screen size.

`.container` vs `@container`

.container controls overall layout max-width (e.g. centering, page width).
@container creates a query container for component-level responsive styles.

Enabling Container Queries in Tailwind v4

If you’re using Tailwind CSS v4.0+, container queries are built-in. For older versions (v3.2/v3.3), install the @tailwindcss/container-queries plugin in your tailwind.config.js.

Using `@container` and Responsive Variants

Markup example:

<div class="@container">
  <p class="text-base @md:text-xl">Container-responsive text</p>
</div>

In this example, the paragraph’s text will be text-base by default, but will automatically enlarge to text-xl as soon as its parent <div> becomes 28rem (448px) wide or more.

The @md: class applies when the parent container reaches the default md size (~28 rem / 448px).

Max-width Container Queries

Tailwind also supports @max-* variants (e.g. @max-md:...) to apply styles when the container is at or below a certain breakpoint.

Range Queries

You can combine min and max variants, such as @sm:@max-md:flex-col to target a specific container width range.

Named Containers & Arbitrary Sizes

Named containers: Use @container/name and target it with variants like @lg/name:... to scope styles to that container.
Arbitrary breakpoints: Tailwind supports inline values like @[500px]:bg-red-100 and @max-[800px]:text-sm for custom container query thresholds

Configuring Container Breakpoints

Tailwind provides default container sizes (@xs to @7xl, ~20rem to 80rem). You can customize or extend them in CSS-first config or via tailwind.config.js theme variables.

Container Queries vs Media Queries

Media queries (sm:, md:) respond to viewport width, while container queries (@sm:, @md:) respond to container width—perfect for component-scoped responsiveness.

Common Use Cases

Responsive cards: Automatically switch layout (vertical/horizontal) based on available width.
Sidebar menus: Collapse or adapt items if sidebar is narrow or expanded.
Widgets or headers: Adjust UI elements like text size or spacing depending on container size.

Tailwind vs Plain CSS

Feature	Tailwind (@container)	Native CSS Implementation
Setup	Built-in in v4 or plugin pre-v4	Manual CSS writing required
Utility naming	`@container`, `@md:` etc.	Hand-coded `@container` rules and `container-type`
Named containers	`@container/name` support	`container-name` property manually
Arbitrary breakpoints	`@[500px]:...` syntax	Hand-coded media queries inside CSS
Fallback support	`supports-` variant or base styles	Manual `@supports` + `@media` fallback blocks

Best Practices & Limitations

Use container queries only on components that benefit from adaptive behavior.
Combine global breakpoints with container queries for scalable responsive design.
Name containers when multiple contexts exist to avoid ambiguity.
Default styles should work without container support (for legacy browsers).
Overusing containers or arbitrary queries can inflate generated CSS.
Tailwind v4 supports width-only container queries—no height-based defaults yet.

Tailwind CSS v4’s container query utilities enable smarter, component-first responsive design using utility classes. By combining @container, responsive @ variants, named containers, and customizable breakpoints, you can build UI components that adapt intelligently to their real layout context—without leaving your markup.

/Michael Andreuzza