lottie-react

Lottie for React

weekly downloads1.7M

versionv2.4.1

licenseMIT

categoryanimation

lottiereactlottie reactreact lottielottie webanimationcomponenthook

Overview

lottie-react is a React wrapper around the lottie-web library that enables developers to integrate Lottie animations—vector animations exported from Adobe After Effects using the Bodymovin plugin—into React applications. With over 1.6 million weekly downloads, it has become the standard solution for rendering lightweight, scalable animations in React web apps. The package exposes both a declarative <Lottie /> component and a useLottie() hook, giving developers flexibility in how they manage animation lifecycle and interactivity.

The library solves the problem of delivering high-quality animations without relying on GIFs or video files, which are typically larger and less flexible. Lottie JSON files are resolution-independent, scriptable, and significantly smaller than traditional formats. lottie-react makes these animations first-class React citizens by handling DOM management, providing ref-based imperative controls, and exposing animation events through props like onComplete and onLoopComplete.

Teams building marketing sites, product tours, loading states, and interactive UI elements choose lottie-react because it eliminates the boilerplate of manually integrating lottie-web with React's lifecycle. It requires React 16.8+ due to hooks usage and supports advanced features like interactivity (scroll/cursor-triggered animations), segment playback, and dynamic property manipulation. The package is framework-specific to React web—React Native projects should use lottie-react-native instead.

Under the hood, lottie-react delegates rendering to lottie-web, which uses either SVG, Canvas, or HTML renderers. This means it inherits both the capabilities (trim paths, masks, expressions) and limitations (CPU-based rendering) of the underlying library. For performance-critical applications with many simultaneous animations, developers may need to optimize by reducing animation complexity or exploring WebAssembly alternatives like @lottiefiles/dotlottie-react.

Quick Start

typescript

import { useRef, useEffect } from 'react';
import Lottie from 'lottie-react';
import successAnimation from './success.json';

function CheckoutSuccess({ onAnimationComplete }) {
  const lottieRef = useRef();

  useEffect(() => {
    if (lottieRef.current) {
      lottieRef.current.setSpeed(1.5);
    }
  }, []);

  const handleComplete = () => {
    setTimeout(() => {
      onAnimationComplete();
    }, 500);
  };

  const handleReplay = () => {
    lottieRef.current?.goToAndPlay(0);
  };

  return (
    <div style={{ textAlign: 'center' }}>
      <Lottie
        lottieRef={lottieRef}
        animationData={successAnimation}
        loop={false}
        autoplay={true}
        style={{ width: 200, height: 200 }}
        onComplete={handleComplete}
      />
      <button onClick={handleReplay}>Replay Animation</button>
    </div>
  );
}

export default CheckoutSuccess;

Use Cases

Loading and skeleton states: Replace spinners with branded loading animations that maintain visual consistency across your application. Pass loop={true} to the component and conditionally render based on loading state, providing users with engaging feedback during data fetches or transitions.

Onboarding flows and feature announcements: Embed animated illustrations in multi-step tutorials or product tours. Use ref methods like play() and stop() to synchronize animation playback with user progression through steps, creating cohesive storytelling experiences.

Interactive hero sections: Implement scroll-triggered or hover-activated animations for landing pages. The interactivity prop enables cursor tracking or scroll-based scrubbing, allowing animations to respond to user input without additional event handlers.

Success and error states: Display confirmation animations after form submissions or checkout processes. Combine with callbacks like onComplete to trigger navigation or state changes once the animation finishes, creating polished micro-interactions.

Data visualization overlays: Animate charts, graphs, or infographic elements to draw attention to key metrics. Control playback speed with setSpeed() and use playSegments() to highlight specific data ranges, making complex information more digestible.

Pros & Cons

Pros

+Modern React API with hooks support and ref-based imperative controls for fine-grained playback management
+Minimal setup overhead—just import the component and pass animationData as a prop without manual DOM manipulation
+Full access to lottie-web methods (play, pause, setSpeed, goToAndStop) through refs, enabling complex interaction patterns
+Supports standard React patterns like spreading HTML div props and integrating with state management libraries
+Active maintenance with 1.6M+ weekly downloads, ensuring compatibility with current React versions and ecosystem tools

Cons

−JavaScript-based rendering via lottie-web can cause performance issues with multiple or complex animations, especially on lower-end devices
−Larger bundle size compared to direct lottie-web usage due to React abstraction layer, though tree-shaking helps
−Limited to web platforms—React Native projects require a separate package (lottie-react-native) with different APIs
−Animation quality depends on After Effects export settings and Bodymovin plugin version, which can introduce compatibility issues
−No built-in TypeScript type exports for ref methods in older versions, requiring manual type assertions for imperative controls

Comparisons

gsap vs lottie-react

animation

Install

bash

npm install lottie-react

bash

pnpm add lottie-react

bash

bun add lottie-react

Overview

Quick Start

typescript

import { useRef, useEffect } from 'react';
import Lottie from 'lottie-react';
import successAnimation from './success.json';

function CheckoutSuccess({ onAnimationComplete }) {
  const lottieRef = useRef();

  useEffect(() => {
    if (lottieRef.current) {
      lottieRef.current.setSpeed(1.5);
    }
  }, []);

  const handleComplete = () => {
    setTimeout(() => {
      onAnimationComplete();
    }, 500);
  };

  const handleReplay = () => {
    lottieRef.current?.goToAndPlay(0);
  };

  return (
    <div style={{ textAlign: 'center' }}>
      <Lottie
        lottieRef={lottieRef}
        animationData={successAnimation}
        loop={false}
        autoplay={true}
        style={{ width: 200, height: 200 }}
        onComplete={handleComplete}
      />
      <button onClick={handleReplay}>Replay Animation</button>
    </div>
  );
}

export default CheckoutSuccess;

Use Cases

Pros & Cons

Pros

+Modern React API with hooks support and ref-based imperative controls for fine-grained playback management
+Minimal setup overhead—just import the component and pass animationData as a prop without manual DOM manipulation
+Full access to lottie-web methods (play, pause, setSpeed, goToAndStop) through refs, enabling complex interaction patterns
+Supports standard React patterns like spreading HTML div props and integrating with state management libraries
+Active maintenance with 1.6M+ weekly downloads, ensuring compatibility with current React versions and ecosystem tools

Cons

−JavaScript-based rendering via lottie-web can cause performance issues with multiple or complex animations, especially on lower-end devices
−Larger bundle size compared to direct lottie-web usage due to React abstraction layer, though tree-shaking helps
−Limited to web platforms—React Native projects require a separate package (lottie-react-native) with different APIs
−Animation quality depends on After Effects export settings and Bodymovin plugin version, which can introduce compatibility issues
−No built-in TypeScript type exports for ref methods in older versions, requiring manual type assertions for imperative controls