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, size:lg, and flex-basis:sm.
• Provide thresholds for @container(<name>) 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;}

The same token can drive a width cap and a container query. That keeps component dimensions and responsive thresholds from drifting apart. Container scale tables read from manifest metadata, so the displayed size and generated query stay aligned when tokens use rem, px, or legacy unitless numbers.

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. Container query variants use the same namespace for thresholds.

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:full max-w:5xl mx:auto">    ...</main><aside class="flex-basis:md flex-shrink:0">...</aside>

@layer theme {    :root {        --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\:full {        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 the element whose inline size should be observed. Then apply @container(<size>) variants to descendants.

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

@layer theme {    :root {        --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\(md\) {            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

Container query variants use the same container-* tokens as sizing utilities.

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

Query container ranges

Use comparison and logical operators when a component needs a bounded range.

<div class="hidden@container(sm&<=md)">...</div>

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

Prefer named container tokens for repeated component states. Use raw container query values only when the threshold belongs to one local component and is unlikely to become part of the shared design language.

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@card(3xs)">...</article></section>

@layer utilities {    .container\:card\/inline-size {        container: card/inline-size    }    @container card (width>=16rem) {        .grid-cols\:2\@card\(3xs\) {            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(md)">...</article></section>

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