react-spring

React Spring is a spring-physics-first animation library for React, published across a small family of packages — @react-spring/web for the DOM and @react-spring/three for react-three-fiber scenes, both built on the same @react-spring/core engine. Instead of tweening between two fixed keyframes with a duration and easing curve, animations are modeled as physical springs with mass, tension, and friction, so motion accelerates and settles the way real objects do, and animations can be freely interrupted and redirected mid-flight without visual snapping.

The library exposes this through a small set of declarative hooks — useSpring, useSprings, useTrail, useTransition, and useChain — plus an animated.* component factory (animated.div, or any host element/component) that receives the animated values as props. Rather than causing a React re-render on every animation frame, react-spring writes the interpolated values straight to the underlying DOM node or three.js object each tick, so 60fps motion doesn’t fight React’s reconciliation. It powers animation in a large number of production sites and libraries in the wild, including projects built on Next.js and react-three-fiber.

What You Get

• A useSpring/useSprings/useTrail/useTransition hook API for declarative, interruption-safe spring animations
• An animated.* component factory that wraps any host element or component so it can receive animated style/props
• Imperative escape hatches (useSpringRef, SpringRef, .start()/.stop()) for animating outside React’s render cycle when needed
• Cross-platform targets — @react-spring/web for DOM/CSS, @react-spring/three for react-three-fiber — sharing one physics core
• A Parallax component (@react-spring/parallax) built entirely on the public hook API for scroll-driven layouts
• A dedicated rafz frame scheduler with separate update/write/onFrame queues so physics stepping and DOM writes stay decoupled from React’s own scheduling

Common Use Cases

• Fade/slide/scale transitions for UI elements entering and leaving the screen
• Interruptible drag-and-release or gesture-driven animations that need to redirect mid-motion without a jump
• List and card transitions (useTransition) for items being added, removed, or reordered
• Chained or staggered sequences (useChain, useTrail) for multi-step onboarding or reveal animations
• Animating 3D object props (position, rotation, material) in a react-three-fiber scene

Under The Hood

Architecture The monorepo is layered cleanly: @react-spring/types and @react-spring/shared (colors, easings, string interpolation, and the rafz-backed frameLoop) sit at the bottom; @react-spring/animated builds a host-agnostic Animated/AnimatedObject tree plus a createHost/withAnimated factory (packages/animated/src/createHost.ts, withAnimated.tsx) that any renderer can plug into; @react-spring/core (packages/core/src/SpringValue.ts, Controller.ts) implements the actual spring math and the public hooks; and targets/web / targets/three supply only the thin, renderer-specific applyAnimatedValues implementation. @react-spring/parallax is a higher-level component built entirely on the public core hooks, proving the layering holds end to end. rafz (packages/rafz/src/index.ts) runs separate update/write/onStart/onFrame/onFinish queues so a single requestAnimationFrame tick can step physics and flush DOM writes in a defined order.

Tech Stack TypeScript throughout, built per-package with tsdown and orchestrated across the workspace with Turborepo and pnpm workspaces. Testing runs on Vitest split into three projects — unit, types (using .test-d.ts/spec.ts files to assert TypeScript inference itself), and e2e via @vitest/browser-playwright for real browser DOM behavior. Linting and formatting run on oxlint/oxfmt (Rust-based tooling) rather than ESLint/Prettier. @react-three/fiber and three are peer dependencies for the three.js target; releases are versioned and published via Changesets, with Husky + commitlint enforcing conventional commits.

Code Quality Every core module (SpringValue, Controller, SpringRef, the interpolation and easing helpers, and each hook) has a colocated .test.ts(x) file, and type-level correctness is tested as a first-class citizen via dedicated .test-d.ts/spec.ts files, not just runtime assertions — an unusually thorough setup. Internal code favors explicit, typed helper functions (helpers.ts, runAsync.ts, AnimationConfig.ts) over ad hoc branching, and misuse is surfaced with developer-facing console warnings (e.g. the forwardRef reminder in withAnimated.tsx) instead of failing silently. CI enforces lint, type-check, and the full multi-project Vitest suite before merge.

API Design The standout technical choice is bypassing React’s render cycle for the animation loop itself: withAnimated writes interpolated values directly onto the DOM node or three.js instance on every rAF tick (via a small pluggable HostConfig.applyAnimatedValues interface) and only forces a React re-render when it actually must, giving CSS-transition-like performance without leaving React’s component model. Because the same SpringValue/Controller core drives both the DOM and three.js targets through this one host interface, the physics engine is written once and reused across renderers. Day-to-day ergonomics stay simple — one hook (useSpring) plus an animated.div is enough to get started — while SpringRef/useSpringRef remain available as an opt-in imperative escape hatch for when render-driven updates aren’t enough.