{"id":11744,"library":"react-lottie-player","title":"React Lottie Player","description":"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.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install react-lottie-player","lang":"bash","label":"npm"},{"cmd":"yarn add react-lottie-player","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-lottie-player","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for any React component library.","package":"react","optional":false}],"imports":[{"note":"The main Lottie player component is a default export, commonly imported as 'Lottie'.","wrong":"import { Lottie } from 'react-lottie-player'","symbol":"Lottie","correct":"import Lottie from 'react-lottie-player'"},{"note":"Use this import path for the 'Light' version, which avoids `eval` for stricter CSPs or SSR, and is also a default export.","wrong":"import { LottiePlayerLight } from 'react-lottie-player'","symbol":"LottiePlayerLight","correct":"import Lottie from 'react-lottie-player/dist/LottiePlayerLight'"},{"note":"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.","wrong":"const lottieRef = useRef(); // Lacks type inference","symbol":"LottieRefCurrent","correct":"const lottieRef = useRef<LottieRefCurrent | null>(null);"}],"quickstart":{"code":"import React, { useEffect, useState, useRef } from 'react';\nimport Lottie from 'react-lottie-player';\n// Alternatively for environments with strict CSPs or SSR, use the 'Light' version:\n// import Lottie from 'react-lottie-player/dist/LottiePlayerLight';\n\ninterface LottieAnimationData {\n  v: string;\n  fr: number;\n  ip: number;\n  op: number;\n  w: number;\n  h: number;\n  nm: string;\n  assets: any[];\n  layers: any[];\n}\n\nconst LottiePlayerExample: React.FC = () => {\n  const [animationData, setAnimationData] = useState<LottieAnimationData | null>(null);\n  const lottieRef = useRef<any>(null); // Type 'any' for simplicity; typically more specific lottie-web instance type\n\n  useEffect(() => {\n    // Dynamically import animation data, useful for code splitting large JSON files\n    import('./my-lottie-animation.json')\n      .then(module => setAnimationData(module.default as LottieAnimationData))\n      .catch(error => console.error('Failed to load Lottie animation:', error));\n  }, []);\n\n  if (!animationData) {\n    return <div>Loading Lottie animation...</div>;\n  }\n\n  return (\n    <div>\n      <h1>My Lottie Animation</h1>\n      <Lottie\n        loop\n        play\n        animationData={animationData}\n        lottieRef={lottieRef}\n        style={{ width: 300, height: 300, border: '1px solid #eee' }}\n        onEvent={(event: string) => {\n          // console.log(`Lottie Event: ${event}`);\n          if (event === 'complete') {\n            console.log('Animation completed!');\n          }\n        }}\n      />\n      <button onClick={() => lottieRef.current?.play()}>Play</button>\n      <button onClick={() => lottieRef.current?.pause()}>Pause</button>\n      <button onClick={() => lottieRef.current?.stop()}>Stop</button>\n      <button onClick={() => lottieRef.current?.setSpeed(lottieRef.current?.getSpeed() * 1.5)}>Speed Up</button>\n    </div>\n  );\n};\n\nexport default LottiePlayerExample;\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"The default `react-lottie-player` bundle uses `eval`, which can violate strict Content Security Policies (CSPs).","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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 });`.","cause":"Attempting to render `react-lottie-player` (or the underlying `lottie-web`) in a Server-Side Rendering (SSR) environment.","error":"ReferenceError: document is not defined"},{"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`).","cause":"Commonly due to an incorrect path or malformed `animationData` object, or an incorrect `loop`/`play` prop value.","error":"Animation not showing / nothing renders, no errors in console"},{"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.","cause":"Mismatched `lottie-web` version types or breaking changes in `lottie-web` that affect `react-lottie-player`'s internal typings.","error":"TypeScript error related to `lottie-web` types (e.g., 'AnimationConfig' is missing properties)"}],"ecosystem":"npm"}