Containers

Use container size tokens for reusable width caps, component dimensions, and container query variants.

Overview

Containers define the size scale for reusable layout surfaces. In Master CSS, the container namespace has two related jobs:

• Provide contextual size values such as max-w-md, w-3xl, width-lg and height-lg, and flex-basis-sm.
• Provide a shared size vocabulary for explicit native container queries, so components can respond to the space they actually receive.

Use breakpoints for viewport-level page changes. Use containers for component-level adaptation and shared width caps.

Define container variables

Container tokens belong in the theme layer and use the container-* namespace.

@theme {  --container-sm: 24rem;  --container-md: 28rem;  --container-7xl: 80rem;}

Use complete query values with explicit units. Container query preludes do not resolve theme tokens or var() references; use a named @custom-variant when a query is shared. The tables show the current token values as complete query examples, preserving their authored units.

Namespace for container values

The container variable namespace is shared by width, height, min and max constraints, flex basis, intrinsic size, and media sizing utilities.

This lets sizing utilities use md, 5xl, or project token names without the container- prefix. Native query values are explicit; they do not search this namespace.

Use container values in sizing utilities

Sizing utilities that read from the container namespace use contextual shorthand. Write max-w-md; do not repeat the namespace inside the value.

<main class="w:100% max-w-5xl mx:auto">  ...</main><aside class="flex-basis-md flex-shrink:0">...</aside>

@layer theme {  :root,  :host {    --container-5xl: 64rem;    --container-md: 28rem  }}@layer utilities {  .mx\:auto {    margin-inline: auto  }  .flex-basis-md {    flex-basis: var(--container-md)  }  .max-w-5xl {    max-width: var(--container-5xl)  }  .w\:100\% {    width: 100%  }}

The shorthand is contextual: md can mean a container value inside max-w-md, and a breakpoint threshold inside @md. The utility or variant decides which namespace is active.

Create a query container

Add container to an ancestor whose inline size comes from the surrounding layout. Then apply full @container((width>=28rem)) queries to its descendants. A size query cannot select the element itself as its query container.

<section class="container">  <article class="grid-cols:1 gap-lg grid-cols:2@container((width>=28rem))">    ...  </article></section>

@layer theme {  :root,  :host {    --spacing-lg: 1.5rem  }}@layer utilities {  .container {    container-type: inline-size  }  .gap-lg {    gap: var(--spacing-lg)  }  .grid-cols\:1 {    display: grid;    grid-template-columns: repeat(1, minmax(0, 1fr))  }  @container (width>=28rem) {    .grid-cols\:2\@container\(\(width\>\=28rem\)\) {      display: grid;      grid-template-columns: repeat(2, minmax(0, 1fr))    }  }}

Container queries make components portable. The same card can be stacked in a sidebar and split into columns in a wide content region without knowing the viewport width.

Container query scale

The following complete queries use values from the preset container scale. Copy a value with its unit, or define a named custom variant for a reusable query.

This is different from viewport breakpoints on purpose. A component threshold is usually smaller than a page threshold. For example, @container((width>=28rem)) can represent a comfortable card width, while @md represents a desktop page shell.

Query container ranges

Use native CSS range and logical operators when a component needs a bounded range.

<div class="hidden@container((24rem<=width<=28rem))">...</div>

@layer utilities {  @container (24rem<=width<=28rem) {    .hidden\@container\(\(24rem\<\=width\<\=28rem\)\) {      display: none    }  }}

For repeated conditions, define @custom-variant card-wide { @container (width>=28rem) { @slot; } } and use @card-wide. Container names are explicit inside the full query; an unknown @name never becomes a container query.

Use named containers

Use named containers when a descendant should query a specific ancestor instead of the nearest container.

<section class="container:card/inline-size">  <article class="grid-cols:2@container(card|(width>=16rem))">...</article></section>

@layer utilities {  .container\:card\/inline-size {    container: card/inline-size  }  @container card (width>=16rem) {    .grid-cols\:2\@container\(card\|\(width\>\=16rem\)\) {      display: grid;      grid-template-columns: repeat(2, minmax(0, 1fr))    }  }}

Named containers are useful in nested layouts, but do not add names everywhere. The default nearest-container behavior is simpler and easier to move between compositions.

Choose caps or queries

Container size values and container queries are related, but they solve different problems.

A reusable card depends on the viewport, so it changes at the wrong time inside narrow parents.

<article class="grid-cols:2@md">...</article>

The card depends on the space it receives.

<section class="container">  <article class="grid-cols:2@container((width>=28rem))">...</article></section>

If a layout rule describes the whole page, use breakpoints. If it describes a reusable component or a wrapper width, use containers.