Sizing Components with Container Query Units

The missing half of component-responsive CSS.

Three container frames hold the same arrangement of component panels, each scaled to its parent container.

Container query units (CQ units) let components respond to the size of their container, not the viewport. They’re a powerful addition to modern CSS, and they open up new, more predictable layout patterns.

Why container query units exist

Media queries and viewport units (vw, vh) helped us design for the browser window. But modern UIs are built from components, and those components can land inside a sidebar, a modal, a grid cell—each with very different available space. Container query units solve the “right sizing” problem by making measurements relative to a query container instead of the viewport.

Quick memory hook: if vw/vh are “viewport percent” units, then cq* are “container percent” units.

What are the container query units?

Unit Meaning (1 unit equals…) When to use
cqi 1% of the container’s inline-size (writing-mode aware width) Typography, gaps, padding that should scale with the container’s inline axis
cqb 1% of the container’s block-size (writing-mode aware height) Vertical spacing, min-heights, block-axis rhythm—when the component’s height matters
cqw 1% of the container’s physical width When you specifically want physical width, regardless of writing mode
cqh 1% of the container’s physical height When you specifically want physical height, regardless of writing mode
cqmin 1% of the smaller of the container’s inline-size and block-size Uniform scaling (e.g., squares, type that shouldn’t overshoot in either axis)
cqmax 1% of the larger of the container’s inline-size and block-size Hero layouts, big decorative pieces that can use the dominant axis

Tip: If you already think in logical properties (inline-size, block-size), you’ll love cqi and cqb. If you prefer physical axes, reach for cqw/cqh.

Before the units: make something a query container

Container units resolve only inside an element that’s been designated a query container. You do that with container-type (or the shorthand container).

.card {
  /* Choose the kind of containment you need */
  container-type: inline-size; /* for cqi/cqw/cqmin/cqmax that depend on inline size */
  /* container-type: size;     /* for both inline + block (enables cqb/cqh as well) */
  /* Optionally name it if you'll @container-query by name */
  container-name: card;
}
  • Use inline-size when you only care about width-ish behavior (most components).
  • Use size when you also need height-aware behavior (for cqb/cqh and cqmax/cqmin across both axes).

Gotcha: If no ancestor establishes an appropriate container-type, the cq* units inside compute as 0. That usually looks like “why is my font-size tiny?”—check your containment.

Mental model: think “percent of my box”

The cq* units are essentially “component percentages.” Just as 10vw is 10% of the viewport width, 10cqi is 10% of the query container’s inline-size. Crucially, the container is the nearest ancestor with compatible containment, and the measurement is taken from its content box (not padding edge).

Once you internalize that, a lot of “make it scale with its parent” problems become one-liners.

Practical examples you’ll actually use

1) Fluid, container-scoped typography

A headline that scales with the card it lives in (not the viewport). Here we clamp between a comfortable minimum and maximum, with a fluid middle driven by the component’s width via cqi.

.card { container-type: inline-size; }

.card__title {
  /*  clamp(min, fluid, max) using the card's inline-size  */
  font-size: clamp(1rem, 2cqi + 0.5rem, 2rem);
  line-height: 1.2;
}

2) Vertical rhythm that adapts to height

If your component’s height meaningfully changes (maybe it’s a sticky sidebar or a tall media card), use cqb to keep vertical spacing proportionate.

.sidebar {
  container-type: size; /* enables block-axis units */
  padding-block: clamp(1rem, 4cqb, 3rem);
  gap: 2cqb;
}

3) Square (or near-square) tiles without math headaches

cqmin is fantastic when you want a square that fits in varying spaces—use the smaller axis so it never overflows.

.gallery { 
  display: grid; 
  grid-template-columns: repeat(auto-fill, minmax(14rem, 1fr));
  gap: 1.25rem;
}
.tile { 
  container-type: size; 
  /* Make the inner media square based on the smaller axis of the tile */
  --u: cqmin; 
}
.tile__media {
  width: calc(80 * var(--u));   /* 80cqmin */
  height: calc(80 * var(--u));  /* 80cqmin */
  border-radius: 1rem;
  object-fit: cover;
}

4) Balanced padding in both axes

Mix inline and block units for padding that feels “balanced” as the card grows or shrinks.

.callout { 
  container-type: size; 
  padding-inline: clamp(1rem, 2.5cqi, 3rem);
  padding-block:  clamp(0.75rem, 2cqb, 2rem);
  border-radius: min(1rem, 3cqi);
}

5) Hero media that scales with the dominant axis

Use cqmax when your design should lean into whichever axis is larger (wide banners vs. tall features).

.hero { container-type: size; }
.hero__headline { font-size: clamp(1.5rem, 4cqmax, 4rem); }
.hero__media    { border-radius: clamp(.5rem, 1.5cqmax, 2rem); }

Inline vs. block: writing-mode aware (or not)

cqi/cqb follow the document’s writing mode (like logical properties do). In horizontal writing modes, inline ≈ width and block ≈ height. In vertical writing modes, those flip. If you want units that ignore writing mode, use cqw/cqh for physical width/height.

Rule of thumb: Prefer cqi/cqb for component logic (they respect internationalization). Reach for cqw/cqh when you truly mean physical width/height.

Combining with clamp() and calc()

Container units shine with mathematical functions. Use clamp() to set safe bounds and calc() to mix container responsiveness with fixed or tokenized spacing.

.chip { 
  container-type: inline-size;
  --pad: clamp(.5rem, .8cqi, 1rem);
  padding: var(--pad) calc(var(--pad) * 1.5);
  font-size: clamp(.75rem, 1.2cqi + .1rem, 1rem);
  border-radius: clamp(.4rem, 1.2cqi, .75rem);
}

Yes, you can combine container units with custom properties like any other length.

Reusable patterns

Pattern: “Proportional spacing”

.stack { container-type: size; }
.stack > * + * { margin-block-start: clamp(0.5rem, 1.2cqb, 1.5rem); }

Pattern: “Scale by the smaller side”

.avatar { 
  container-type: size; 
  inline-size: min(100%, 20rem);
  aspect-ratio: 1;
  border-radius: 50%;
  /* keep border readable regardless of shape */
  outline: solid clamp(2px, .6cqmin, 6px) currentColor;
}

Pattern: “Context-aware fluid type tokens”

:root {
  /* fallback tokens if a component isn't in a container yet */
  --step-0: 1rem; 
  --step-1: 1.125rem;
}

.card { container-type: inline-size; }

/* when inside a container, redefine tokens using cqi */
.card {
  --step-0: clamp(0.95rem, 1cqi + 0.25rem, 1.125rem);
  --step-1: clamp(1.05rem, 1.6cqi + 0.3rem, 1.35rem);
}

.card h3   { font-size: var(--step-1); }
.card p    { font-size: var(--step-0); }

Common gotchas & troubleshooting

  • Units resolve to 0? Ensure an ancestor has container-type. For cqb/cqh, you specifically need container-type: size.
  • Nothing changes on resize? The container itself must change size. A fixed-width parent means your cqi is constant.
  • Spacing feels “off” in vertical writing modes? Switch from cqw/cqh to cqi/cqb, which follow writing mode.
  • Nested components fighting each other? The nearest ancestor with containment “wins.” Consider naming containers (container-name) for clarity in your @container rules, even if you’re using units alone.
  • Paddings vs. content box: cq* units measure the container’s content box, not including padding. If your math seems slightly off, check padding on the container.

FAQ

Do I need @container to use container units?

Nope. Units work independently of conditional queries. You only need a query container (via container-type), not necessarily any @container rules.

Which units should I prefer by default?

Use cqi for most width-ish scaling (text, gaps, inline padding). Add cqb when vertical rhythm should track height. Use cqmin for “never overflow” geometry and cqmax for bold, dominant-axis elements.

Can I mix cq* units with tokens and rems?

Absolutely. Most robust systems blend fixed primitives (e.g., rem) with fluid container-based values using calc() and clamp().

Wrap-up: component-first, not page-first

Container query units let your components “breathe” with the space they’re given. Instead of tuning everything to a single viewport, you size type, paddings, radii, and media relative to the actual box that contains them. Once you add a simple container-type, many sizing problems collapse into elegant one-liners.

If you’ve already adopted @container for conditional styling, consider this the other half of the story: units that make components fluid by default—no conditions needed.