Container Query Units cqw/cqh/cqi — Free CSS Snippet

For years, responsive typography and spacing in CSS had exactly one relative axis to work with: the viewport. Units like vw, vh, and vmin let a value scale with the browser window, but they had no concept of the actual space available to the element using them. A card in a 240px sidebar and a card in a 1200px main column would compute the exact same vw-based font-size, because vw has no idea it's sitting inside a narrow container. Container query units fix this at the root: they are relative units that resolve against the size of the nearest ancestor established as a query container, not the browser viewport.

How a query container is established

An element becomes a query container by setting container-type on it — most commonly container-type: inline-size, which tracks only the element's inline dimension (width in a horizontal writing mode). You can optionally name it with container-name so nested queries can target a specific ancestor rather than the nearest one. In this demo, .resizable-container has container-type: inline-size; container-name: demo-card; applied, which is what makes every cq* unit used by its descendants resolve against *that box's* width rather than the window's.

The unit vocabulary: cqw, cqh, cqi, cqb, cqmin, cqmax

Once an ancestor is a query container, descendants can use cqw (1% of the container's width), cqh (1% of the container's height), cqi (1% of the inline-size — width in normal horizontal writing modes, so functionally identical to cqw in most layouts but writing-mode aware), cqb (1% of the block-size), cqmin (the smaller of cqi/cqb), and cqmax (the larger). This demo uses font-size: 8cqi on .cqi-text — meaning the heading is always exactly 8% of the container's current inline-size. Drag the width slider from 160px to 820px and watch the readout: at 520px the text computes to 41.6px (520 × 0.08); at 300px it drops to 24px. The math is linear and live because the browser recalculates cqi on every layout pass, the same way it recalculates vw.

Why the vw sibling doesn't move

The right-hand box in this demo uses font-size: 3.5vw and sits *outside* any query container. Resizing the left card's width has zero effect on it — vw only reads window.innerWidth, which the JS in this demo also displays via a resize listener for comparison. This side-by-side contrast is the core lesson: viewport units answer "how big is the browser window," while container query units answer "how big is *this specific box*, wherever it happens to be placed."

Why this matters for real component libraries in 2025/2026

Design systems increasingly ship components meant to be dropped into wildly different contexts — a product card might render in a 3-column grid, a narrow sidebar widget, or a full-width hero. Before container query units, achieving a self-scaling card required either JavaScript-driven ResizeObserver logic or brittle breakpoint-based media queries tied to the *page's* width rather than the *component's* width. Container query units, paired with the @container at-rule for conditional layout switches, let a single component author its own internal responsive behavior declaratively, in CSS alone, correctly scoped to wherever it's mounted — including inside CMS-driven pages, dashboard widgets, and email-client-style embedded panels where you don't control the outer page structure.

Browser support and pairing with clamp()

Container query units and container-type shipped in all major evergreen browsers (Chrome, Edge, Safari, Firefox) starting in 2023, and by 2025 they're safe for production use without fallbacks in virtually any modern browser target. A common refinement is wrapping a cq unit inside clamp(), e.g. font-size: clamp(1rem, 8cqi, 3rem), so the text still scales fluidly with the container but never shrinks below a legible floor or balloons past a sane ceiling — the same pattern used in the companion Fluid Typography with clamp() snippet, just swapping the middle argument's unit from vw to cqi.