Motion That Scales with Container Size: cqi, cqb, and Derived Durations

A slide-in written as translateX(300px) is really a statement about one particular layout — the one that happened to be on screen when the number was chosen. Put the same component into a 280px sidebar card and the declaration becomes absurd: the element travels further than the box that holds it, arriving either clipped by overflow: hidden or on top of whatever sits alongside. This page is about replacing that constant with a measurement the browser can take at style time — container query units in translate() and @keyframes, plus durations computed from the same figure — so a single motion rule is correct at every width. It sits inside the container-aware motion section and depends directly on the unit mechanics set out in container query units cqi and cqb explained.

Why the fixed pixel is wrong, and why CSS is the right place to fix it

The perceptual point is not that 300px is too many pixels. It is that the eye evaluates travel relative to the moving object's surroundings, in roughly the same way it evaluates type size relative to measure. A 300px slide across a 1200px hero covers a quarter of the space and reads as a considered entrance. The identical 300px inside a 280px card covers more than the whole component, and the brain does not interpret it as a bigger version of the same gesture — it interprets it as an error, a thing flying off. Somewhere between those two extremes the same number stops describing the same motion.

There are three ways to make travel track the box. A ResizeObserver can measure the element and write a custom property; that works, but it costs a script, an observation callback per component, and a frame of latency during which the old distance is still in effect — plus it can desynchronise from layout when the main thread is busy. Percentage values in translate() are the classic CSS answer and are genuinely useful, but they resolve against the transformed element's own border box, not its container, which is the wrong reference whenever the element does not fill its slot. Container query units resolve against the query container, which is exactly the reference the design intends, and they cost nothing beyond ordinary style computation.

The tradeoff worth stating plainly: container units make travel proportional, and proportional is not always what you want. A focus ring offset, a 1px border shift, or a checkbox tick should stay at a fixed size regardless of context, because they are absolute affordances rather than compositional gestures. Scale distances that describe layout relationships — entrances, reveals, panel slides, hover lifts — and leave absolute detail alone. And proportional travel has no lower bound of its own, so at very small container sizes it converges on zero-ish values that read as vibration rather than movement; that end of the range needs the explicit treatment described in suppressing motion in small containers.

Complete working implementation

The example below is a direct comparison bench. Two identical rails each establish their own query container. The top marker animates a hard-coded 180px; the bottom animates 70cqi. At a wide frame both look fine. Drag the frame narrower and the top marker runs into and past the rail's clipping edge, while the bottom marker keeps stopping at 70% of whatever width the rail currently has.

<div class="bench">
  <p class="bench__label">travel: 180px (fixed)</p>
  <div class="rail"><span class="marker marker--fixed"></span></div>

  <p class="bench__label">travel: 70cqi (container-relative)</p>
  <div class="rail"><span class="marker marker--fluid"></span></div>
</div>

.rail {
  container-type: inline-size;   /* each rail is its own query container */
  position: relative;
  height: 44px;
  margin-bottom: 1.1rem;
  border: 1px dashed var(--demo-border);
  border-radius: 8px;
  overflow: hidden;              /* proves when the fixed run overshoots */
}

.marker {
  position: absolute;
  top: 10px; left: 10px;
  width: 24px; height: 24px;
  border-radius: 6px;
  background: var(--demo-accent);
}

/* Distance baked in at author time — wrong the moment the rail is narrow. */
.marker--fixed { animation: run-fixed 2.4s ease-in-out infinite alternate; }
@keyframes run-fixed { to { transform: translateX(180px); } }

/* Distance resolved against the rail's own inline size. */
.marker--fluid { animation: run-fluid 2.4s ease-in-out infinite alternate; }
@keyframes run-fluid { to { transform: translateX(70cqi); } }

.bench__label {
  margin: 0 0 .35rem;
  color: var(--demo-muted);
  font: 12px ui-monospace, monospace;
}

The --demo-* values above are the theme variables supplied by the demo frame, so the example follows light and dark mode here. Substitute your own colour tokens when you copy it.

The important structural detail is that container-type: inline-size is on .rail and the animated element is .marker inside it. An element cannot query or measure against itself; the 70cqi in the keyframe resolves against the nearest ancestor that is a query container. Drop the container-type line and the animation does not break — it silently starts measuring against the viewport instead, which is the single most confusing failure mode in this whole technique.

The key technique: a length for distance, a ratio for time

Distance and duration need opposite treatments, and mixing them up is where most implementations fall over.

Distance takes the unit directly. cqi is a <length>, so it drops into translateX(), translateY(), inset, margin, or a keyframe declaration with no conversion at all. transform: translateX(70cqi) is as valid as translateX(70px). There is no calc() required and no intermediate custom property needed.

Duration cannot. A <time> cannot be produced by multiplying a length, so calc(400ms * 6cqi) is invalid, the declaration is dropped, and the element falls back to the initial 0s — which looks exactly like having forgotten to write a transition at all. The fix is to reduce the container measurement to a unitless ratio first — but note that dividing a container unit by a number does not do it: 1.6cqi / 10 is still a length, and clamp() will not mix a length with the plain numbers bounding it, so that whole declaration is invalid too. The conversion that works is tan(atan2(1cqi, 1px)), which returns the ratio of two lengths as a real <number>. Bound that, then multiply a base time by it:

.panel {
  /* tan(atan2()) turns the container length into a real number; clamp bounds it to 0.5 – 1.4. */
  --cqi-ratio: tan(atan2(1cqi, 1px));
  --room: clamp(0.5, calc(var(--cqi-ratio) * 0.16), 1.4);

  --slide: clamp(12px, 8cqi, 64px);        /* a length, used directly */
  --beat:  calc(140ms * var(--room));      /* a time, built from the ratio */

  transition: transform var(--beat) cubic-bezier(.2, .8, .2, 1);
}
.panel[data-open] { transform: translateX(calc(-1 * var(--slide))); }

The clamp() around the distance is doing separate work from the clamp() around the ratio. The distance clamp stops the gesture becoming either invisible in a tiny box or theatrical in a very wide one. The ratio clamp keeps the duration inside the range where interaction still feels responsive — a purely proportional duration in a 1600px container would stretch past the point where a hover response feels immediate. Pairing a longer distance with a longer time is what keeps velocity constant, which is the quantity the eye is actually judging; the easing curve choice that goes with it is covered in CSS transition timing functions.

Variation: vertical travel, and why cqb is usually the wrong reach

The obvious move for a vertical slide is cqb, which measures 1% of the container's block size. It works, but it carries a condition: block-axis measurement requires container-type: size, which applies containment on both axes and therefore demands that the container have a determinate height. Applied to an ordinary auto-height card, container-type: size collapses the box to nothing, and the resulting bug — a container that measures zero, so every cqb distance is zero, so nothing moves — is deeply unfun to diagnose. The distinction is worked through in container-type: size vs inline-size.

In practice, sizing vertical travel from the inline axis is both safe and defensible: a component that is wide is generally a component with room, and vertical entrance distances that scale with width look correct because the component's overall scale is what changed.

/* Vertical entrance whose distance follows the container's width. */
.notice { animation: rise-in 320ms cubic-bezier(.2, .8, .2, 1) both; }

@keyframes rise-in {
  from { opacity: 0; transform: translateY(clamp(8px, 4cqi, 28px)); }
  to   { opacity: 1; transform: translateY(0); }
}

/* Reserve cqb for containers that genuinely have a fixed height. */
.viewport-strip {
  container-type: size;
  block-size: 320px;               /* determinate — required for cqb */
}
.viewport-strip .ticker { animation: drop 5s linear infinite; }
@keyframes drop { to { transform: translateY(90cqb); } }

@media (prefers-reduced-motion: reduce) {
  .notice, .viewport-strip .ticker { animation: none; }
}

The reduced-motion block is not optional decoration. Proportional travel produces larger movements in exactly the contexts — wide, full-bleed regions — where large movements are most likely to cause discomfort, so the preference override matters more here than it does with fixed distances. The full set of override shapes is in reducing motion preferences in CSS.

Browser support

Container query units ship with size container queries and have the same support floor: Chrome and Edge 105+, Safari 16+, Firefox 110+, giving interoperable support since Firefox's release in February 2023. Their use inside transform and inside @keyframes is not a separate feature — they are lengths, and every engine that resolves them resolves them everywhere a length is accepted. clamp() predates all of this comfortably and is supported across every current engine.

The graceful-degradation story is unusually benign. In an engine without container query support, 70cqi falls back to the equivalent small-viewport unit rather than being discarded, so motion still happens — it is simply sized against the window. If you need something better than "wrong reference but still animated", gate the proportional rules behind @supports (container-type: inline-size) and supply a fixed-pixel default outside it, as set out in feature detection with @supports.

FAQ

Why does a 300px slide look wrong in a 280px card? The travel exceeds the component itself, so the element leaves its own box and either clips against overflow or overlaps its neighbours. Even at 200px the movement reads as the whole component jumping rather than a detail sliding, because the eye judges travel as a fraction of the moving object's container.

Can container query units appear inside @keyframes? Yes. Keyframe declarations accept lengths like any other declaration, so transform: translateX(70cqi) inside a keyframe is valid and resolves against the animated element's query container at style computation time.

How do I turn a container width into an animation duration? Divide the container unit down into a unitless ratio inside clamp(), then multiply a base time by that ratio with calc(). A length can never be multiplied directly into a time value, so the intermediate unitless step is mandatory.

Should I use cqi or cqb for vertical movement? Usually cqi even for vertical movement, because cqb requires container-type: size, which contains the block axis and needs a determinate height. Sizing vertical travel from the inline axis is stable and avoids the collapsed-container problem.

Related

• Container-Aware Motion — the parent section on sizing motion to the component's own box.
• Suppressing Motion in Small Containers — what to do at the bottom of the scale, where proportional travel stops reading.
• Container Query Units cqi and cqb Explained — the cross-area reference for the units used throughout.
• Fluid Space Scale with clamp() — the same clamping arithmetic applied to spacing tokens.
• Fluid Spacing Tokens Driving Transition Durations — sharing one token between layout and timing across a design system.