Chapter 9: Container Queries

Core Idea

@container marks an element as a query container so its descendants can be styled with @sm:/@md:-style variants based on that container's own size, not the viewport — making components portable and reusable regardless of where they're placed in a layout.

Key Concepts

• Enabling a container: add the @container class to a wrapper; its children can then use @{size}: variants (@md:flex-row) to respond to that container's width, mobile-first (applies at that size and up) just like viewport breakpoints.
• Max-width container variants: @max-sm:, @max-md:, etc. apply below a given container size — the container-query equivalent of max-* breakpoint variants.
• Ranges: stack a min and max container variant (@sm:@max-md:flex-col) to scope a style to a specific container-size window.
• Named containers: @container/{name} names a container so nested content can target a specific ancestor container instead of the nearest one, via @sm/{name}: — needed when containers are nested and you must reach past the closest one.
• Size containers: @container alone only tracks inline-size (width). Use @container-size when you need container query units that depend on block-size too (e.g. h-[50cqb]); also nameable (@container-size/{name}).
• Container query length units: cqw/cqi (and cqb/cqh with a size container) can be used directly as arbitrary values in any utility (w-[50cqw]), not just inside @container variants.
• Custom container sizes: --container-* theme variables (@theme { --container-8xl: 96rem; }) add new named container-size variants (@8xl:), same mechanism as --breakpoint-*.
• Arbitrary container sizes: @min-[475px]:/@max-[960px]: for one-off sizes not worth adding to the theme.

Code Examples

<div class="@container">
  <div class="flex flex-col @md:flex-row @sm:@max-md:flex-col">
    
  </div>
</div>

<div class="@container/sidebar">
  <div class="@sm/sidebar:flex-row">
    
  </div>
</div>

• What it demonstrates: basic container-responsive layout with a range override, and reaching past the nearest container using a named one.

Reference Tables

Variant	Min container width		Variant	Min container width
@3xs	16rem (256px)		@2xl	42rem (672px)
@2xs	18rem (288px)		@3xl	48rem (768px)
@xs	20rem (320px)		@4xl	56rem (896px)
@sm	24rem (384px)		@5xl	64rem (1024px)
@md	28rem (448px)		@6xl	72rem (1152px)
@lg	32rem (512px)		@7xl	80rem (1280px)
@xl	36rem (576px)

Key Takeaways

1. Reach for container queries instead of viewport breakpoints when a component's layout should depend on the space it's actually given (sidebar vs. main column, reusable card in different-width slots), not the whole page width.
2. @container alone is inline-size-only — add @container-size only when you specifically need block-size-dependent units (cqb/cqh).
3. Named containers (@container/name) are the escape hatch for nested containers where the default "nearest ancestor" targeting isn't the one you need.

Connects To

• Responsive Design: the same mobile-first, range-stacking, and theme-customization mental model applies, just scoped to a container instead of the viewport.
• Theme: --container-* variables follow the same @theme customization pattern as --breakpoint-*.