useTrail and useChain for Sequences

useTrail(count, config) creates count springs that animate in sequence with a configurable delay between each one. When the trail starts, the first item animates immediately, the second starts slightly after, the third after that, and so on — creating a fan-out or cascade effect.

useTrail returns an array of spring objects, one for each item in the trail. Each spring has the same shape (same keys) but starts its animation at a different time offset. You map over both the trail array and your items array simultaneously to render each animated item with its corresponding spring.

Render a trailed list by mapping over the trail array: trail.map((spring, i) => React.createElement(animated.div, { style: spring, key: items[i].id }, items[i].content)). Each animated.div receives its own spring object, so items animate in sequence. The springs run in index order: 0, 1, 2, 3...

useTrail supports a toggle pattern for forward and reverse animation. Pass a boolean open state to control direction: when open is true, trail animates from hidden to visible; when false, it reverses from visible to hidden. The trail reverses order automatically — items animate out in reverse sequence (last in, first out).

The config object for useTrail is the same as useSpring: tension, friction, mass. The delay between items is determined by how long each spring takes to start, which is controlled by the overall spring physics. Stiffer springs with higher tension create faster staggering; gentler springs create longer cascades.

useSpringRef() creates a ref that you attach to a spring hook via its ref option. The ref gives useChain control over when that spring starts. You create one ref per spring or trail that you want to sequence: const springRef = useSpringRef(), then pass it: useSpring({ ref: springRef, ... }).

useChain([ref1, ref2, ref3], [0, 0.5, 0.8]) sequences multiple springs or trails. The first argument is an array of springRefs in the order they should play. The second argument is an array of timestamps between 0 and 1, indicating when each spring starts as a fraction of the total timeframe.

In useChain, timestamps like [0, 0.5] mean spring 1 starts at 0% through the sequence and spring 2 starts at 50% through. The optional third argument is the total timeframe in milliseconds (default 1000ms). So with [0, 0.5] and 2000ms, spring 1 starts at 0ms and spring 2 starts at 1000ms.

A common pattern: animate a container expanding (useSpring for size) and then animate items inside fading in (useTrail for list). Attach refs to both, then use useChain([sizeRef, trailRef], [0, 0.5]) so the container expands first, then items fade in halfway through. This creates a cinematic two-phase entrance animation.

useChain is ideal for page transitions. When navigating between pages, chain the exit animation of the old page with the entrance animation of the new page. The exit completes first (timestamp 0), then the entrance begins (timestamp 0.6). This creates a smooth handoff rather than abrupt switching.

useTrail can create parallax scroll effects by animating items at different speeds based on their position in the trail. Items deeper in the trail start later and may have different config (lower tension), causing them to move more slowly. This depth-based timing simulates the parallax effect of objects at different distances.

How does useTrail create the staggered delay between items in the animation?

useTrail(count, config) creates count springs that animate in sequence, creating staggered list entrances. Map over trail and items simultaneously to render. useSpringRef() creates refs that useChain uses for sequencing. useChain([ref1, ref2], [0, 0.5]) orchestrates multiple springs with fractional timestamps. Together they enable complex multi-phase sequences like expand-then-reveal animations.