skip to content

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?

level: middleimportance: should knowfreq 13%

answer

  1. query the parent, not the screen
  2. mark the ancestor first
  3. a separate size scale
  4. @max-* and stacked ranges
  5. a slash name for a distant container

basics

~20 s

In 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 s

Container-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

for a junior

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.

for a middle

Explain what each class emits and compiles to, including @max-* caps, stacked ranges, arbitrary sizes and named containers with the slash form.

for a senior

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.

for a principal

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.