@react-spring/web

`react-dom` support

weekly downloads3.3M

versionv10.0.3

licenseMIT

categoryanimation

animatedanimationhooksmotionreactreact-nativespringtypescriptvelocity

Overview

@react-spring/web is the web-specific implementation of React Spring, a library that brings spring-physics-based animations to React applications. Unlike traditional duration-based animation libraries, it simulates real-world physics using configurable spring parameters (tension, friction, mass) to create natural, fluid motion. With over 3.3 million weekly downloads, it's become the go-to solution for developers who need performant, declarative animations that feel organic rather than mechanical.

The library is built around React hooks like useSpring, useTransition, and useChain, allowing you to create animations that respond to state changes, user interactions, and complex orchestrations. It renders to standard DOM elements (HTML and SVG) through animated components that accept interpolated values for styles, transforms, and even CSS variables. The API supports both declarative patterns (where animations trigger on render) and imperative control (via the returned API object) for event-driven scenarios.

React Spring v10 is part of a platform-agnostic architecture that shares core animation logic across @react-spring/three (for WebGL/Three.js), @react-spring/native (for React Native), and web targets. This means you can use consistent APIs whether animating DOM nodes, 3D scenes, or mobile UI components. The library automatically batches updates for efficient React reconciliation and includes features like per-property callbacks, animation chaining, and gesture integration.

The package is written in TypeScript and ships with full type definitions. It includes preset configurations (config.wobbly, config.stiff, etc.) for common animation styles and supports custom spring configurations for precise control. While it doesn't include built-in gesture handlers like dragging or pinching, it provides hooks like useDrag and integrates well with external gesture libraries.

Quick Start

typescript

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

function AnimatedCard() {
  const [isFlipped, setIsFlipped] = useState(false);
  const [items, setItems] = useState(['Item 1', 'Item 2', 'Item 3']);

  // Spring animation for card flip
  const { transform, opacity } = useSpring({
    opacity: isFlipped ? 1 : 0.6,
    transform: `perspective(600px) rotateY(${isFlipped ? 180 : 0}deg)`,
    config: config.wobbly,
  });

  // Transition for list items
  const transitions = useTransition(items, {
    from: { opacity: 0, transform: 'translate3d(-40px,0,0)' },
    enter: { opacity: 1, transform: 'translate3d(0,0,0)' },
    leave: { opacity: 0, transform: 'translate3d(40px,0,0)' },
    keys: item => item,
  });

  const addItem = () => {
    setItems([...items, `Item ${items.length + 1}`]);
  };

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

  return (
    <div style={{ padding: '2rem' }}>
      <animated.div
        onClick={() => setIsFlipped(!isFlipped)}
        style={{
          width: 200,
          height: 200,
          background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
          borderRadius: 12,
          cursor: 'pointer',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          color: 'white',
          fontSize: 24,
          fontWeight: 'bold',
          opacity,
          transform,
        }}
      >
        {isFlipped ? 'Back' : 'Front'}
      </animated.div>

      <div style={{ marginTop: '2rem' }}>
        <button onClick={addItem}>Add Item</button>
        {transitions((style, item) => (
          <animated.div
            style={{
              ...style,
              padding: '1rem',
              marginTop: '0.5rem',
              background: '#f0f0f0',
              borderRadius: 8,
              display: 'flex',
              justifyContent: 'space-between',
              alignItems: 'center',
            }}
          >
            <span>{item}</span>
            <button onClick={() => removeItem(item)}>Remove</button>
          </animated.div>
        ))}
      </div>
    </div>
  );
}

export default AnimatedCard;

Use Cases

Page Transition Animations: Animate route changes in single-page applications with useTransition to smoothly mount/unmount components. Handle enter/exit states for modals, sidebars, or full-page navigations with spring physics that feels more natural than CSS transitions.

Interactive UI Elements: Create responsive buttons, cards, or toggles that animate on hover, click, or focus. Use useSpring with imperative API control to trigger animations based on user events, with spring physics automatically handling interruptions mid-animation without jarring stops.

List Reordering and Filtering: Animate items entering, leaving, or shuffling position in dynamic lists using useTransition. Common in dashboards, task managers, or e-commerce catalogs where items get added, removed, or sorted, with each element smoothly transitioning to its new position.

Scroll-Linked Animations: Drive animations based on scroll position by combining useSpring with scroll event listeners. Create parallax effects, sticky headers with morphing states, or reveal animations that respond to viewport position with spring-dampened motion instead of linear interpolation.

Form Validation Feedback: Animate error states, success indicators, or input field transformations (shake on error, expand on focus) using spring physics. Provide tactile feedback that feels responsive and helps guide users through complex forms or multi-step workflows.

Pros & Cons

Pros

+Spring-physics creates natural, organic motion that adapts automatically when interrupted—no manual timing curve adjustments needed
+Hook-first API integrates cleanly with modern React patterns; supports both declarative and imperative animation control in the same project
+Cross-platform architecture allows shared animation logic between web, React Native, and Three.js with minimal code changes
+Efficient rendering with automatic batched updates and ability to bypass React reconciliation for high-frequency animations
+TypeScript support with complete type definitions; extensive preset configurations reduce boilerplate for common animation patterns

Cons

−Larger bundle size (~50kb gzipped) compared to simpler CSS-in-JS animation solutions or native CSS transitions
−Spring physics requires tuning tension/friction values to achieve specific timing—less intuitive than duration-based APIs for developers used to traditional easing
−No built-in gesture handlers (drag, pinch, swipe)—requires integration with external libraries or manual event handling for complex interactions
−Documentation can be fragmented across platform-specific packages; v9 to v10 migration introduced breaking changes that affect older tutorials
−Performance can degrade with hundreds of simultaneously animating elements without manual optimization via keys and memoization

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

Install

bash

npm install @react-spring/web

bash

pnpm add @react-spring/web

bash

bun add @react-spring/web

Overview

Quick Start

typescript

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

function AnimatedCard() {
  const [isFlipped, setIsFlipped] = useState(false);
  const [items, setItems] = useState(['Item 1', 'Item 2', 'Item 3']);

  // Spring animation for card flip
  const { transform, opacity } = useSpring({
    opacity: isFlipped ? 1 : 0.6,
    transform: `perspective(600px) rotateY(${isFlipped ? 180 : 0}deg)`,
    config: config.wobbly,
  });

  // Transition for list items
  const transitions = useTransition(items, {
    from: { opacity: 0, transform: 'translate3d(-40px,0,0)' },
    enter: { opacity: 1, transform: 'translate3d(0,0,0)' },
    leave: { opacity: 0, transform: 'translate3d(40px,0,0)' },
    keys: item => item,
  });

  const addItem = () => {
    setItems([...items, `Item ${items.length + 1}`]);
  };

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

  return (
    <div style={{ padding: '2rem' }}>
      <animated.div
        onClick={() => setIsFlipped(!isFlipped)}
        style={{
          width: 200,
          height: 200,
          background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
          borderRadius: 12,
          cursor: 'pointer',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          color: 'white',
          fontSize: 24,
          fontWeight: 'bold',
          opacity,
          transform,
        }}
      >
        {isFlipped ? 'Back' : 'Front'}
      </animated.div>

      <div style={{ marginTop: '2rem' }}>
        <button onClick={addItem}>Add Item</button>
        {transitions((style, item) => (
          <animated.div
            style={{
              ...style,
              padding: '1rem',
              marginTop: '0.5rem',
              background: '#f0f0f0',
              borderRadius: 8,
              display: 'flex',
              justifyContent: 'space-between',
              alignItems: 'center',
            }}
          >
            <span>{item}</span>
            <button onClick={() => removeItem(item)}>Remove</button>
          </animated.div>
        ))}
      </div>
    </div>
  );
}

export default AnimatedCard;

Use Cases

Pros & Cons

Pros

+Spring-physics creates natural, organic motion that adapts automatically when interrupted—no manual timing curve adjustments needed
+Hook-first API integrates cleanly with modern React patterns; supports both declarative and imperative animation control in the same project
+Cross-platform architecture allows shared animation logic between web, React Native, and Three.js with minimal code changes
+Efficient rendering with automatic batched updates and ability to bypass React reconciliation for high-frequency animations
+TypeScript support with complete type definitions; extensive preset configurations reduce boilerplate for common animation patterns

Cons

−Larger bundle size (~50kb gzipped) compared to simpler CSS-in-JS animation solutions or native CSS transitions
−Spring physics requires tuning tension/friction values to achieve specific timing—less intuitive than duration-based APIs for developers used to traditional easing
−No built-in gesture handlers (drag, pinch, swipe)—requires integration with external libraries or manual event handling for complex interactions
−Documentation can be fragmented across platform-specific packages; v9 to v10 migration introduced breaking changes that affect older tutorials
−Performance can degrade with hundreds of simultaneously animating elements without manual optimization via keys and memoization