Registry / web-framework / react-lottie-player

react-lottie-player

JSON →
library2.1.0jsnpmunverified

React Lottie Player is a component library for integrating Lottie animations into React applications with a fully declarative API. It wraps the core `lottie-web` library, aiming to provide a more robust experience by correctly handling prop changes for playback control and claiming to prevent memory leaks often associated with `lottie-web` repeaters. The current stable version, `2.1.0`, was published approximately two years ago, suggesting a mature and stable but not rapidly updated codebase for this specific package. Key differentiators include its declarative nature, seamless control of animation states (play, pause, loop, segments) via props, and the provision of a `LottiePlayerLight` variant that avoids the use of `eval` for environments with strict Content Security Policies.

npm install react-lottie-player
INSTALL
IMPORT
SIG · REACT-LOTTIE-PLAYE
R
react-lottie-player
web-frameworkjavascriptv2.1.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Lottie
import Lottie from 'react-lottie-player'
import { Lottie } from 'react-lottie-player'
The main Lottie player component is a default export, commonly imported as 'Lottie'.
LottiePlayerLight
import Lottie from 'react-lottie-player/dist/LottiePlayerLight'
import { LottiePlayerLight } from 'react-lottie-player'
Use this import path for the 'Light' version, which avoids `eval` for stricter CSPs or SSR, and is also a default export.
LottieRefCurrent
const lottieRef = useRef<LottieRefCurrent | null>(null);
const lottieRef = useRef(); // Lacks type inference
For imperative control via `useRef`, you'll likely interact with the underlying `lottie-web` instance, which benefits from type hinting. `LottieRefCurrent` is an internal type that represents the lottie-web instance.

This quickstart demonstrates how to import and render a Lottie animation using `react-lottie-player`. It shows loading animation data asynchronously, setting common props like `loop` and `play`, applying styles, and using a ref for imperative playback control (play, pause, stop, speed). It includes type definitions for clarity.

import React, { useEffect, useState, useRef } from 'react'; import Lottie from 'react-lottie-player'; // Alternatively for environments with strict CSPs or SSR, use the 'Light' version: // import Lottie from 'react-lottie-player/dist/LottiePlayerLight'; interface LottieAnimationData { v: string; fr: number; ip: number; op: number; w: number; h: number; nm: string; assets: any[]; layers: any[]; } const LottiePlayerExample: React.FC = () => { const [animationData, setAnimationData] = useState<LottieAnimationData | null>(null); const lottieRef = useRef<any>(null); // Type 'any' for simplicity; typically more specific lottie-web instance type useEffect(() => { // Dynamically import animation data, useful for code splitting large JSON files import('./my-lottie-animation.json') .then(module => setAnimationData(module.default as LottieAnimationData)) .catch(error => console.error('Failed to load Lottie animation:', error)); }, []); if (!animationData) { return <div>Loading Lottie animation...</div>; } return ( <div> <h1>My Lottie Animation</h1> <Lottie loop play animationData={animationData} lottieRef={lottieRef} style={{ width: 300, height: 300, border: '1px solid #eee' }} onEvent={(event: string) => { // console.log(`Lottie Event: ${event}`); if (event === 'complete') { console.log('Animation completed!'); } }} /> <button onClick={() => lottieRef.current?.play()}>Play</button> <button onClick={() => lottieRef.current?.pause()}>Pause</button> <button onClick={() => lottieRef.current?.stop()}>Stop</button> <button onClick={() => lottieRef.current?.setSpeed(lottieRef.current?.getSpeed() * 1.5)}>Speed Up</button> </div> ); }; export default LottiePlayerExample;
Debug
Known issues
breakingVersion 2.0.0 introduced 'typescript improvements' that could be breaking for existing TypeScript setups. Always review your type definitions and usage when upgrading from v1.x to v2.x.
fix
Consult the package's changelog and update your TypeScript types and component props accordingly. Ensure your `animationData` object conforms to the expected `lottie-web` JSON structure.
affects: >=2.0.0
gotchaThe default `react-lottie-player` bundle uses `eval`, which can violate strict Content Security Policies (CSPs).
fix
To avoid `eval`, import the `LottiePlayerLight` variant specifically: `import Lottie from 'react-lottie-player/dist/LottiePlayerLight'`. This version offers the same declarative API without using `eval` internally.
affects: >=1.0.0
gotchaWhen using `react-lottie-player` in Server-Side Rendering (SSR) environments like Next.js, you may encounter `ReferenceError: document is not defined` as `lottie-web` (the underlying library) relies on browser APIs.
fix
Implement dynamic imports or lazy loading for the `Lottie` component, ensuring it's only rendered on the client side. For example, in Next.js, use `next/dynamic` with `ssr: false`.
affects: >=1.0.0
gotchaWhile `react-lottie-player` claims to address memory leaks from `lottie-web` when using repeaters, complex animations or frequent mounting/unmounting of the player can still be resource-intensive.
fix
Monitor application performance, especially in scenarios with many animations or dynamic component lifecycles. Consider optimizing animation JSONs, using `LottiePlayerLight`, or carefully managing when animations are loaded and rendered (e.g., using intersection observers for animations off-screen).
affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: document is not defined
Attempting to render `react-lottie-player` (or the underlying `lottie-web`) in a Server-Side Rendering (SSR) environment.
fix
Wrap the `Lottie` component with a dynamic import that disables SSR. In Next.js, this is `const DynamicLottie = dynamic(() => import('react-lottie-player'), { ssr: false });`.
Animation not showing / nothing renders, no errors in console
Commonly due to an incorrect path or malformed `animationData` object, or an incorrect `loop`/`play` prop value.
fix
Double-check the `animationData` prop. Ensure it's a valid Lottie JSON object, correctly imported, and that `play` is set to `true`. Verify the `style` prop allows the component to be visible (e.g., has `width` and `height`).
TypeScript error related to `lottie-web` types (e.g., 'AnimationConfig' is missing properties)
Mismatched `lottie-web` version types or breaking changes in `lottie-web` that affect `react-lottie-player`'s internal typings.
fix
Ensure `react-lottie-player` is compatible with your installed `lottie-web` version (if manually installed). Review `react-lottie-player`'s `package.json` for its `lottie-web` peer dependency. If issues persist, consider explicitly installing a compatible version of `@types/lottie-web` or `lottie-web` itself, or reporting an issue to the `react-lottie-player` maintainers.
Upgrade
Version history
2.1.0latest on npm
Audit
Dependencies
reactrequiredPeer dependency required for any React component library.
Agent activity
4 hits · last 30 days
node
4
Resources