react-spring — Physics-Based Animation Library for React

Introduction

react-spring is an animation library that uses spring physics instead of fixed durations and easing curves. The result is motion that feels natural and responsive, automatically adapting when targets change mid-animation rather than snapping or restarting.

What react-spring Does

• Animates any numeric CSS property, SVG attribute, or custom value using spring physics
• Provides hooks (useSpring, useSprings, useTrail, useTransition, useChain) for different patterns
• Supports gesture-driven animation when paired with @use-gesture/react
• Renders through multiple targets: DOM, React Native, Three.js, and Konva
• Handles mount/unmount transitions with automatic enter and leave animations

Architecture Overview

react-spring runs an animation loop outside of React's render cycle using a shared FrameLoop. Each spring maintains a current value and velocity, updating on every frame by solving a damped spring equation. The animated higher-order component subscribes to spring values and applies them directly to the DOM via refs, bypassing React re-renders for performance.

Self-Hosting & Configuration

• Install the target-specific package: @react-spring/web, @react-spring/native, or @react-spring/three
• Import hooks and the animated factory from the installed package
• Configure spring behavior with config presets (default, gentle, stiff, slow) or custom mass, tension, friction
• Combine with @use-gesture/react for drag, pinch, and scroll-driven animations
• Use useChain to orchestrate sequential animations across multiple springs

Key Features

• Physics-driven motion that interrupts and redirects gracefully mid-animation
• Platform-agnostic: works with DOM, React Native, react-three-fiber, and more
• Micro-bundle architecture lets you import only the target you need
• Declarative API with imperative escape hatches via the api object
• Supports CSS variables, scroll-linked values, and SVG path morphing

Comparison with Similar Tools

• Framer Motion — Higher-level API with layout animations; react-spring offers more control over physics parameters
• GSAP — Timeline-based with duration and easing; react-spring uses spring physics for interruptible motion
• anime.js — Vanilla JS timeline animations; no React integration or spring model
• React Transition Group — Manages mount/unmount CSS classes; react-spring handles the actual animation values
• Motion One — Lightweight Web Animations API wrapper; smaller scope than react-spring's full hook suite

FAQ

Q: When should I choose react-spring over Framer Motion? A: Choose react-spring when you need fine-grained control over spring physics, multi-target rendering (Three.js, Native), or want to avoid the larger Framer Motion bundle.

Q: Does react-spring cause extra re-renders? A: No. Animated values update the DOM directly through refs, bypassing React's reconciler for smooth 60fps performance.

Q: Can I animate route transitions? A: Yes. Use useTransition with your router's location object to animate page enter and leave states.

Q: Does it support server-side rendering? A: Yes. Springs resolve to their from or to values on the server and hydrate correctly on the client.

Sources

• https://github.com/pmndrs/react-spring
• https://www.react-spring.dev/