react-spring

weekly downloads838K

versionv10.0.3

licenseMIT

categoryfrontend

animatedanimationhooksmotionreactreact-nativespringtypescriptvelocity

Overview

react-spring is a spring-physics animation library for React applications that prioritizes natural motion over eased keyframes. Instead of defining durations and cubic-bezier curves, you configure tension, friction, and mass to create animations that feel responsive and organic. The library achieves high performance by animating outside React's render cycle—animated values update directly in the browser without triggering component re-renders for each frame.

Built with a hooks-first API, react-spring provides primitives like useSpring for single-value animations, useSprings for coordinating multiple items, useTrail for staggered sequences, and useTransition for mount/unmount lifecycles. It works across React web, React Native, react-three-fiber (Three.js), and other platforms through unified interfaces. Version 9+ introduced platform-specific exports (@react-spring/web, @react-spring/native) and imperative controls via the returned API object.

The library is widely adopted in production applications requiring smooth interactions—dashboards with animated charts, mobile apps with gesture-driven UI, 3D visualizations, and design systems. With 837k weekly downloads, it's maintained as a core animation solution for teams that need more control than CSS transitions but want to avoid manually managing requestAnimationFrame loops. The physics model handles interruptions gracefully: if a user triggers a new animation mid-flight, springs naturally redirect without jarring resets.

react-spring interpolates numbers, colors, transforms, and arbitrary string patterns. You can animate CSS properties, SVG attributes, or custom object values. Advanced features include per-property callbacks (onRest fires when individual keys settle), chained sequences (useChain), and nested SpringContext for scoped animation control like pausing specific subtrees.

Quick Start

typescript

import { useSpring, useTransition, animated, config } from '@react-spring/web';
import { useState } from 'react';

function AnimatedList() {
  const [items, setItems] = useState([{ id: 1, text: 'Task 1' }]);
  const [isExpanded, setIsExpanded] = useState(false);

  // Single spring for container expansion
  const containerSpring = useSpring({
    height: isExpanded ? 400 : 80,
    backgroundColor: isExpanded ? '#f0f0f0' : '#ffffff',
    config: config.wobbly
  });

  // Transitions for list items with stagger
  const transitions = useTransition(items, {
    keys: item => item.id,
    from: { opacity: 0, transform: 'translateX(-40px)' },
    enter: { opacity: 1, transform: 'translateX(0px)' },
    leave: { opacity: 0, transform: 'translateX(40px)' },
    trail: 100
  });

  const addItem = () => {
    const newId = Math.max(...items.map(i => i.id), 0) + 1;
    setItems([...items, { id: newId, text: `Task ${newId}` }]);
  };

  const removeItem = (id) => {
    setItems(items.filter(item => item.id !== id));
  };

  return (
    <div>
      <button onClick={() => setIsExpanded(!isExpanded)}>
        {isExpanded ? 'Collapse' : 'Expand'}
      </button>
      <animated.div
        style={{
          ...containerSpring,
          overflow: 'hidden',
          padding: '20px',
          borderRadius: '8px'
        }}
      >
        {isExpanded && (
          <>
            <button onClick={addItem}>Add Task</button>
            {transitions((style, item) => (
              <animated.div
                style={{
                  ...style,
                  padding: '10px',
                  margin: '5px 0',
                  background: 'white',
                  borderRadius: '4px',
                  display: 'flex',
                  justifyContent: 'space-between'
                }}
              >
                <span>{item.text}</span>
                <button onClick={() => removeItem(item.id)}>Remove</button>
              </animated.div>
            ))}
          </>
        )}
      </animated.div>
    </div>
  );
}

Use Cases

Interactive card reveals: Animate card height, opacity, and transform on user hover or scroll events with useSpring, allowing interruptions when users rapidly hover multiple cards without animation queuing.

List transitions with staggered enter/exit: Use useTransition to handle adding/removing items from filtered lists (search results, todo items), with each item animating in with a slight delay via trail configurations for polished micro-interactions.

Gesture-driven drawers and sheets: Combine imperative API methods (set, start, stop) with touch/drag handlers to create bottom sheets or side drawers that follow finger position with spring physics applying when released, snapping open or closed based on velocity.

Dashboard metric counters: Animate numeric values (revenue figures, user counts) from old to new states using useSpring with number interpolation, making data updates feel less abrupt in analytics interfaces.

3D scene interactions with react-three-fiber: Animate camera positions, object rotations, or material properties in Three.js scenes using the same spring API, creating smooth transitions between different view states in product configurators or data visualizations.

Pros & Cons

Pros

+Physics-based motion feels more natural than duration-based easing, with automatic velocity preservation during interruptions
+Animates outside React render cycle using direct style updates, avoiding performance bottlenecks from frequent re-renders
+Cross-platform compatibility (web, native, Three.js) with unified API surface and platform-specific optimizations
+Imperative API alongside declarative hooks provides escape hatches for complex coordination without fighting the framework
+Rich interpolation system handles transforms, colors, and custom value types with inline composition

Cons

−Spring configuration (tension, friction, mass) requires experimentation—less intuitive than duration milliseconds for designers
−Bundle size around 30-40kb (minified) is larger than CSS-only solutions or lighter animation libs like react-transition-group
−Learning curve for concepts like useChain sequencing and trail offsets steeper than simpler animate-on-mount libraries
−TypeScript types for animated components can be complex when wrapping custom components or third-party elements
−Documentation examples sometimes lack edge cases like handling cleanup in StrictMode or concurrent rendering scenarios

Alternatives

framer-motionv12.34.2

A simple and powerful JavaScript animation library

animationreact animationreact

22.4M / week

gsapv3.14.2

GSAP is a framework-agnostic JavaScript animation library that turns developers into animation superheroes. Build high-performance animations that work in **every** major browser. Animate CSS, SVG, canvas, React, Vue, WebGL, colors, strings, motion paths,

animationGSAPGreenSock

1.8M / week

Comparisons

framer-motion vs react-spring

animation

Install

bash

npm install react-spring

bash

pnpm add react-spring

bash

bun add react-spring

Overview

Quick Start

typescript

import { useSpring, useTransition, animated, config } from '@react-spring/web';
import { useState } from 'react';

function AnimatedList() {
  const [items, setItems] = useState([{ id: 1, text: 'Task 1' }]);
  const [isExpanded, setIsExpanded] = useState(false);

  // Single spring for container expansion
  const containerSpring = useSpring({
    height: isExpanded ? 400 : 80,
    backgroundColor: isExpanded ? '#f0f0f0' : '#ffffff',
    config: config.wobbly
  });

  // Transitions for list items with stagger
  const transitions = useTransition(items, {
    keys: item => item.id,
    from: { opacity: 0, transform: 'translateX(-40px)' },
    enter: { opacity: 1, transform: 'translateX(0px)' },
    leave: { opacity: 0, transform: 'translateX(40px)' },
    trail: 100
  });

  const addItem = () => {
    const newId = Math.max(...items.map(i => i.id), 0) + 1;
    setItems([...items, { id: newId, text: `Task ${newId}` }]);
  };

  const removeItem = (id) => {
    setItems(items.filter(item => item.id !== id));
  };

  return (
    <div>
      <button onClick={() => setIsExpanded(!isExpanded)}>
        {isExpanded ? 'Collapse' : 'Expand'}
      </button>
      <animated.div
        style={{
          ...containerSpring,
          overflow: 'hidden',
          padding: '20px',
          borderRadius: '8px'
        }}
      >
        {isExpanded && (
          <>
            <button onClick={addItem}>Add Task</button>
            {transitions((style, item) => (
              <animated.div
                style={{
                  ...style,
                  padding: '10px',
                  margin: '5px 0',
                  background: 'white',
                  borderRadius: '4px',
                  display: 'flex',
                  justifyContent: 'space-between'
                }}
              >
                <span>{item.text}</span>
                <button onClick={() => removeItem(item.id)}>Remove</button>
              </animated.div>
            ))}
          </>
        )}
      </animated.div>
    </div>
  );
}

Use Cases

Pros & Cons

Pros

+Physics-based motion feels more natural than duration-based easing, with automatic velocity preservation during interruptions
+Animates outside React render cycle using direct style updates, avoiding performance bottlenecks from frequent re-renders
+Cross-platform compatibility (web, native, Three.js) with unified API surface and platform-specific optimizations
+Imperative API alongside declarative hooks provides escape hatches for complex coordination without fighting the framework
+Rich interpolation system handles transforms, colors, and custom value types with inline composition

Cons

−Spring configuration (tension, friction, mass) requires experimentation—less intuitive than duration milliseconds for designers
−Bundle size around 30-40kb (minified) is larger than CSS-only solutions or lighter animation libs like react-transition-group
−Learning curve for concepts like useChain sequencing and trail offsets steeper than simpler animate-on-mount libraries
−TypeScript types for animated components can be complex when wrapping custom components or third-party elements
−Documentation examples sometimes lack edge cases like handling cleanup in StrictMode or concurrent rendering scenarios