react-spring

When to use this

• You want animation values that respond to changing targets continuously and naturally (a value that keeps chasing a target as the target itself changes, like a draggable following a cursor) rather than fixed-duration tweens.
• You need list mount/unmount animation (useTransition) with physically-based enter/leave motion, an alternative to AnimatePresence if you are not otherwise using Motion for React.
• You need cascading/staggered physics-based motion across a list where each item's spring visibly lags the previous one (useTrail).
• You need to interpolate multiple independent spring values into one derived output (e.g. combine x and y springs into a single transform string) via to().
• Do NOT use this when duration-based, precisely-timed sequencing (exact overlaps, labels, scrubbing) is the actual requirement; springs do not have a fixed duration by design, which makes them the wrong tool for gsap-core-timelines-style choreography where exact timing matters more than physical feel.

Mental model

react-spring's fundamental unit of animation is not a duration-based tween but a damped harmonic oscillator: every animated value is modeled as a mass attached to a spring pulling it toward a target, with tension (spring stiffness) and friction (damping) as the two primary tunable forces, plus mass affecting inertia. Because it is a physical simulation stepped every frame rather than a pre-computed interpolation over a fixed time window, a spring naturally handles a target value changing mid-animation: it does not need to be told to reverse or replan, it simply keeps being pulled toward wherever the target currently is, which produces continuous, natural-feeling motion when a drag position or other live input updates the target frequently.

useSpring returns a single animated value object; internally in current react-spring, this is powered by "SpringValues" which, similar to Motion's motion values, can update the DOM directly via an internal animated component wrapper (animated.div etc, from @react-spring/web) without necessarily forcing a full React re-render on every frame, which is why react-spring performs well for continuously-updating values despite React's own render model not being frame-rate-oriented.

useSprings is the array/list form: instead of one spring, it manages N springs (one per item) with a function-based config, letting each item have its own independently-configured or independently-triggered spring while sharing the same hook call and update mechanism, essential for lists where you programmatically re-trigger a subset of items' animations (e.g. re-render triggers a stagger recompute) without manually calling useSpring N times.

useTrail is a specific choreography built on the same multi-spring foundation: each item's spring target is derived from (chases) the PREVIOUS item's current animated value rather than all chasing the same static target independently, which is what produces the visible "each one lags slightly behind the one before it" cascading follow effect, physically different from a stagger()-delayed group of otherwise-identical tweens (which all start at fixed offsets but move independently) since a trail's items are continuously coupled to their neighbor throughout the whole motion, not just at the start.

useTransition solves the same "animate before actually removing from the DOM" problem AnimatePresence solves, but built spring-first: it tracks a list of items across renders (by key), and for items that disappear from the input array, keeps rendering them (calling your render-prop with their leave state) until their leave spring completes, then actually removes them; items newly appearing animate from their from state to enter.