Web development
Container queries with Tailwind
Container queries style a component by its parent's width, not the viewport: @container on the parent, @sm or @md on the children.
Key points
- A container query follows the width of the parent, not the viewport.
- In Tailwind 4 the @sm, @md and @lg variants are built in, with no plugin.
- An @container element cannot size itself from its content.
A container query in Tailwind CSS uses @container on the parent and @sm: or @md: on the children: the style follows the width of the container, not the width of the window.
How to write it
Scheda
Testo che resta leggibile in una colonna stretta.
@container writes container-type: inline-size on the parent. The @md: variant starts at 28rem of container width, which is 448px, and like a breakpoint it is mobile-first: it stays on above that size.
Why breakpoints are not enough
With md: the card changes at the width of the window, not when the real space is too narrow. The same card inside a three-column grid or a sidebar breaks: a container query reads the space it actually has.
Named containers
...
...
Without a name the nearest ancestor container wins. With @container/main and @lg/main: you target one exact container, even a distant one: that is the case for a section with a sidebar.
The default sizes
| Variant | Minimum width |
|---|---|
| @sm | 24rem (384px) |
| @md | 28rem (448px) |
| @lg | 32rem (512px) |
| @xl | 36rem (576px) |
| @3xl | 48rem (768px) |
For a size you use once there are @min-[475px]: and @max-[960px]:. Container units work as arbitrary values: w-[50cqw] fills half the width of the container.
The limitation
An element with @container can no longer size itself from its content: inline-axis containment forbids it. It needs an explicit width, a flex-1 or a grid that fixes it. And the responsive test stays mandatory inside every slot the component lands in.
Where to continue
The catalogue holds the container components, the grid category and the feature-1 block from bag/ui, with cards in a grid. The comparison of the two layout systems is in flexbox and grid for designers, the framework comparison in Tailwind vs Bootstrap; if a variant is not generated, read content paths.
Frequently asked questions
What is the difference between a container query and a media query?
A container query reads the width of the nearest container, a media query reads the width of the window. A card in a narrow column changes even on a wide screen, because the space it has is small.
Do container queries need a plugin in Tailwind?
No in Tailwind 4: @container and the @sm and @md variants ship with the framework. Tailwind 3 needed the @tailwindcss/container-queries plugin, which is no longer required.
At what width does the @md variant start?
The @md variant starts at 28rem of container width, which is 448px. The default sizes run from @3xs at 16rem to @7xl at 80rem.
Can I use a container query for fluid text?
Yes, with the cqw and cqi units. A value such as w-[50cqw] or a font size in cqi scales with the container instead of the window, so the text stays in proportion with the card.
Do older browsers support container queries?
Modern browsers have supported them since 2023, Safari included from version 16. A browser without support ignores the variants and shows the base style, so the layout stays readable.