CSS Container Query Units: Support, Units, Examples

What are CSS container query units?

CSS container query units are six relative length units defined in the W3C CSS Conditional Rules Module Level 5: cqw, cqh, cqi, cqb, cqmin, and cqmax. Each unit equals one percent of a parent query container's width, height, inline size, block size, smaller axis, or larger axis.

Which browsers support CSS container query units?

CSS container query units work in every browser that supports CSS container queries, with Chrome and Edge first in version 105, Safari in version 16, and Firefox in version 110.

What are the available CSS container query units?

The CSS Conditional Rules Module Level 5 defines six container query length units. Each unit measures one percent of a parent container's width, height, inline size, block size, smaller axis, or larger axis, and falls back to the small viewport unit on its axis when no eligible container is found.

• cqw: One percent of the query container's width. If the container is 800px wide, 50cqw equals 400px. cqw always tracks the physical horizontal axis, regardless of writing-mode.
• cqh: One percent of the query container's height. If the container is 300px tall, 10cqh equals 30px. cqh always tracks the physical vertical axis, regardless of writing-mode.
• cqi: One percent of the query container's inline size. cqi equals cqw in horizontal writing modes and cqh in vertical writing modes, so a component sized in cqi flips axes when the page switches to a vertical script like Japanese tate-chu-yoko.
• cqb: One percent of the query container's block size. cqb equals cqh in horizontal writing modes and cqw in vertical writing modes. Pair cqb with cqi for layouts that adapt to writing-mode.
• cqmin: The smaller of cqi or cqb. If the container is 800px wide and 300px tall in horizontal writing-mode, 50cqmin equals 150px. cqmin keeps a square or aspect-ratio-locked element from stretching beyond the shorter axis.
• cqmax: The larger of cqi or cqb. With the same 800 by 300 container, 50cqmax equals 400px. cqmax sizes hero badges and full-bleed media against the longer axis of the container.

How do you use CSS container query units?

Container query units only resolve inside a query container, so the parent must declare container-type before any cq value works. Once the container is declared, any descendant can use cqw, cqh, cqi, cqb, cqmin, or cqmax in place of vw or vh.

• Declare a container on the parent: Set container-type: inline-size for width-based sizing, or container-type: size for both axes. inline-size is the safer default since size also containment forces the block axis and can collapse children with no fixed height.
• Pick the right unit for the axis: Use cqi for inline sizing that adapts to writing-mode, cqw for fixed horizontal sizing, cqb for block-axis sizing, and cqmin or cqmax for symmetric scaling on both axes.
• Wrap cq values in clamp() or calc() for safe ranges: font-size: clamp(1rem, 4cqi, 1.5rem) keeps the font readable when the container is very small or very large, instead of letting cq scale linearly past usable sizes.
• Combine cq units with @container size queries: Use cq units for fluid sizing inside the container, and @container (min-width: 480px) blocks for layout shifts that flip from a single column to a grid.
• Verify the rule fires in DevTools: Open the Elements panel in Chrome 105+ or Safari 16+, click the container badge next to the parent, and resize the container to confirm cqw, cqh, cqi, and cqb update at the right breakpoint.

/* Step 1: Declare a container on the parent */
.product-card {
  container-type: inline-size;
  container-name: card;
}

/* Step 2: Use cq units so children scale with the card, not the viewport */
.product-card h2 {
  font-size: clamp(1rem, 4cqi, 1.5rem);
  padding-inline: 2cqi;
}

.product-card .thumbnail {
  width: 100cqw;
  aspect-ratio: 16 / 9;
}

/* Step 3: Combine cq units with @container size queries for layout shifts */
@container card (min-width: 480px) {
  .product-card {
    display: grid;
    grid-template-columns: 40cqi 1fr;
    gap: 2cqi;
  }
}

If a cq value resolves to the viewport instead of the container, container-type is missing on the closest ancestor; the closest container with container-type wins, so check the cascade in DevTools.

What are the known issues with CSS container query units?

CSS container query units are stable across modern browsers, but the spec has a few traps that catch teams the first time they ship cq values in production.

• cq units fall back to the small viewport unit: If no ancestor declares container-type, every cq value resolves against the small viewport (sv*) on its axis, so 100cqw renders as 100svw. The fallback is silent and produces a layout that looks correct on desktop but breaks inside narrow containers.
• inline-size containers expose only the inline axis: A container with container-type: inline-size resolves cqi, cqw, cqmin, and cqmax against the container, but cqh and cqb fall back to the viewport. Use container-type: size when a child needs both axes, and accept the block-axis containment that comes with it.
• cq units cannot be used in @container conditions: The condition list inside @container (min-width: 30cqi) is invalid. cq units only resolve inside descendant rules, so the breakpoint values must be px, rem, em, or another absolute or font-relative unit.
• Containers cannot size themselves with their own cq units: A container's own width or height cannot reference its own cqw or cqh, since container-type triggers layout containment and would create a circular dependency. Apply cq sizing to descendants only.
• Logical-property bugs in early Safari 16 builds: Safari 16.0 and 16.1 had cases where cqi and cqb resolved against the viewport when the container used display: contents. The fix shipped in Safari 16.4, so set the testing baseline at Safari 16.4 if cqi sizing is critical.
• No fallback inside @container: Browsers older than Chrome 105, Edge 105, Firefox 110, or Safari 16 skip the entire @container block, so any layout the block sets is lost. Provide a baseline outside the @container with px, rem, or vw values for older browsers.

In my experience, the small-viewport fallback bites teams the most. A card that renders correctly on a desktop preview suddenly looks giant inside a 320px sidebar, because the inline-size container higher up the tree got removed during a refactor and every cqi value silently switched to svi. The fix is to add a regression test that asserts a known cqw value matches the parent width, not the viewport.

Citations

All CSS container query unit version numbers and platform notes in this guide come from these primary sources:

• W3C - CSS Conditional Rules Module Level 5 (Container Relative Lengths): drafts.csswg.org/css-conditional-5/#container-lengths
• W3C - CSS Containment Module Level 3: w3.org/TR/css-contain-3
• MDN Web Docs - length value type (container query length units): developer.mozilla.org/en-US/docs/Web/CSS/length
• MDN Web Docs - CSS container queries guide: developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_queries
• MDN Web Docs - @container at-rule: developer.mozilla.org/en-US/docs/Web/CSS/@container
• web.dev - Container queries learn module: web.dev/learn/css/container-queries
• Chrome for Developers - :has() and container queries in Chromium 105: developer.chrome.com/blog/has-with-cq-m105
• WebKit - CSS Container Queries in Safari 16: webkit.org/blog/13152/css-container-queries-in-safari-16
• Apple Developer - Safari 16 Release Notes: developer.apple.com/documentation/safari-release-notes/safari-16-release-notes
• Mozilla - Firefox 110 Release Notes: mozilla.org/en-US/firefox/110.0/releasenotes
• Chrome Platform Status - CSS Container Queries: chromestatus.com/feature/5031719352270848