In Tailwind CSS v4, how do `@container`, `@sm:` and named containers like `@container/main` make a sidebar reflow by its own width instead of the viewport's?
answer
- query the parent, not the screen
- mark the ancestor first
- a separate size scale
- @max-* and stacked ranges
- a slash name for a distant container
basics
~20 sIn Tailwind CSS v4, the @container class makes an element an inline-size query container, and @sm: on its descendants compiles to @container (width >= 24rem). Naming it @container/main and using @sm/main: targets that container rather than the nearest one.
solid answer
~50 sContainer-query variants are built into Tailwind CSS v4; v3 needed a separate plugin. Put the `@container` class on the ancestor whose width matters; it sets `container-type: inline-size`. Descendants then use `@sm:`, `@md:` and so on, which compile to `@container (width >= …)`, so a recipe sidebar reflows by the width it is given, not by the viewport. They are **mobile-first** like breakpoints: `@md:` means at least that container size. `@max-md:` caps it, `@sm:@max-md:` gives a range, and `@min-[475px]:` takes a one-off size. The sizes come from their own container scale (`@sm` is 24rem by default, where the `sm:` breakpoint is 40rem). Without a name, a variant queries the nearest container ancestor; `@container/main` plus `@sm/main:` targets a specific one. An element cannot query itself, so the `@container` class and the `@sm:` classes go on different elements.
go deeper
Recall the two parts: @container on the parent, then @sm: or @md: on the children, and that these sizes are container sizes, not screen breakpoints.
Explain what each class emits and compiles to, including @max-* caps, stacked ranges, arbitrary sizes and named containers with the slash form.
Diagnose variants that never fire: no container ancestor, a variant on the container itself, a nearer container intercepting the query, or the two size scales confused.
Decide which components in a shared library adapt to their container rather than the viewport, and make naming containers a convention for nested layouts.
## Why a sidebar needs container variants A recipe page's **sidebar** of related recipes might render 18rem wide beside the article on a desktop and full width under it on a tablet. A breakpoint variant such as `md:` asks about the **viewport**, which says nothing about the space the sidebar actually has. **Container queries** ask about an **ancestor's** size instead, and Tailwind CSS v4 builds them in; in v3 the same feature came from a separate official plugin. ## Marking the container The `@container` **utility** turns an element into a query container: | Class | Emits | |---|---| | `@container` | `container-type: inline-size` | | `@container/main` | `container-type: inline-size; container-name: main` | How `container-type` affects layout is a CSS concern; for the variants, what matters is that something above the styled element must carry this class. ## The variants and what they compile to | Variant | Compiles to | Applies | |---|---|---| | `@sm:` | `@container (width >= 24rem)` | container at least `sm` | | `@max-md:` | `@container (width < 28rem)` | container below `md` | | `@sm:@max-md:` | both conditions | between `sm` and `md` | | `@sm/main:` | `@container main (width >= 24rem)` | the container named `main` | | `@min-[475px]:` | `@container (width >= 475px)` | a one-off size | Like breakpoints, they are **mobile-first**: an unprefixed utility is the narrow layout and `@md:` layers on changes from that size up. ```html <aside class="@container"> <ul class="grid grid-cols-1 gap-3 @sm:grid-cols-2 @xl:grid-cols-3"> <li>Lemon risotto</li> </ul> </aside> ``` ## Two scales that look alike The `@`-prefixed variants use the **container scale**, not the breakpoint scale. With the default theme, `@sm` is 24rem while `sm:` is 40rem, and the container scale runs from `@3xs` (16rem) up to `@7xl`. Reading `@sm:` as "the same width as `sm:`" is the most common mistake. Adding or changing container sizes is theme configuration. ## The nearest container, or a named one An unnamed variant queries the **nearest ancestor that is a container**. In nested layouts that can be the wrong one: a recipe card inside the sidebar might be its own container, and a variant on the card's title would then answer to the card rather than the sidebar. Naming solves it: 1. mark the outer element `@container/main`; 2. write the variant as `@sm/main:` on any descendant, however deep; 3. the rule now compiles to `@container main (…)` and skips the closer, unnamed container. ## Pitfalls to recognise - **Variants on the container itself.** `<aside class="@container @md:p-6">` does not respond to the aside's own width, because a container query looks at an ancestor container. Put `@container` on a wrapper, or move the variant to a child. - **No container at all.** Without an ancestor marked `@container`, the variants never apply. - **Confusing the scales.** `@md:` (28rem container) and `md:` (48rem viewport) are unrelated widths. - **Expecting `@md:` to stop at `@lg`.** It never stops; cap it with a `@max-*` variant. - **Reaching for a plugin.** v4 needs none; the variants are part of the framework. ## Turning a breakpoint layout into a container layout To convert an existing component: 1. find the element whose width really governs the component, often its wrapper, and add `@container` there, named if containers will nest; 2. replace viewport variants inside the component with container variants, choosing each size from the container scale rather than copying the breakpoint name, because the same name means a different width; 3. keep page-level decisions, such as whether the sidebar sits beside the article, on breakpoint variants; 4. check the component in every place it is used, since it now adapts to each slot independently. Container query length units such as `cqw` and `cqi` can also be used as arbitrary values in other utilities, sizing something relative to the container. ## When to use which Use **breakpoint variants** for page-level layout that genuinely depends on the viewport, such as whether the sidebar sits beside the article. Use **container variants** inside a component that is placed in containers of different widths, such as the related-recipes list, so the same markup adapts wherever it is placed.
- Why does `<aside class="@container @md:p-6">` never get the extra padding, however wide it is?A container query evaluates against an ancestor container, so an element cannot respond to its own container size. The aside is the container, so its own `@md:p-6` has nothing above it to query. Wrap the content in a child that carries `@md:p-6`, or put `@container` on a parent of the aside.
- A card inside the sidebar is also a container. How do you make the card's title react to the sidebar's width?Name the sidebar, `@container/sidebar`, and use `@md/sidebar:` on the title. An unnamed variant queries the nearest container ancestor, which is now the card; the named form compiles to `@container sidebar (width >= …)` and targets the sidebar, however deep the title is nested.
- @sm: uses the same width as the sm: breakpoint
- an element marked @container can use @md: to react to its own width
- container variants need a plugin in Tailwind CSS v4
- an unnamed @sm: variant queries the outermost container on the page
- @max-md: applies from the md container size upward
Assumes Tailwind CSS v4 (checked at 4.3.3); container-query variants and the @container utility are built in since v4, where v3 needed a separate plugin.