React Lottie Player

Common errors

• ReferenceError: document is not defined

  cause 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

  cause 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)

  cause 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.

Warnings

• breaking Version 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.
• gotcha The 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.
• gotcha When 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`.
• gotcha While `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).

Install

• npm install react-lottie-player npm
• yarn add react-lottie-player yarn
• pnpm add react-lottie-player pnpm

Imports

• Lottie
  wrong:

  import { Lottie } from 'react-lottie-player'

  correct:

  import Lottie from 'react-lottie-player'

  The main Lottie player component is a default export, commonly imported as 'Lottie'.
• LottiePlayerLight
  wrong:

  import { LottiePlayerLight } from 'react-lottie-player'

  correct:

  import Lottie from 'react-lottie-player/dist/LottiePlayerLight'

  Use this import path for the 'Light' version, which avoids `eval` for stricter CSPs or SSR, and is also a default export.
• LottieRefCurrent
  wrong:

  const lottieRef = useRef(); // Lacks type inference

  correct:

  const lottieRef = useRef<LottieRefCurrent | null>(null);

  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.

Quickstart

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;