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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Lottie
✓ import Lottie from 'lottie-react';
✗ import { Lottie } from 'lottie-react';
The `Lottie` component is a default export. Incorrectly importing it as a named export is a common mistake.
useLottie
✓ import { useLottie } from 'lottie-react';
✗ import useLottie from 'lottie-react';
The `useLottie` hook is a named export, primarily used for greater control over the animation instance.
useLottieInteractivity
✓ import { useLottieInteractivity } from 'lottie-react';
✗ import useLottieInteractivity from 'lottie-react';
This hook provides functionality for interactive Lottie animations based on cursor or scroll events, available since v2.1.0.
RendererType
✓ import type { RendererType } from 'lottie-react';
✗ import type { RendererType } from 'lottie-web';
Type export for Lottie renderer options, exposed via lottie-react since v2.4.0 for convenience and type safety.
Demonstrates the basic usage of the Lottie component to display a looping animation from a local JSON file.
import React from 'react';
import Lottie from 'lottie-react';
import groovyWalkAnimation from './groovyWalk.json'; // Ensure you have a Lottie JSON animation file
const App = () => {
return (
<div style={{ width: 300, height: 300, margin: 'auto' }}>
<Lottie animationData={groovyWalkAnimation} loop={true} />
</div>
);
};
export default App;
Debug
Known issues
breakingThe `ref` property on the `Lottie` component, previously used to export interaction methods for the animation instance, was renamed to `lottieRef`.fixIf accessing the Lottie animation instance methods, change `ref` to `lottieRef`. The `ref` prop now refers to the animation container's DOM element.
affects: >=2.0.0
gotchalottie-react leverages React Hooks, requiring `react` and `react-dom` versions `16.8.0` or newer.fixEnsure your project's `react` and `react-dom` peer dependencies are updated to `^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0`.
affects: <16.8.0 (for React)
gotchaOlder versions of the library (prior to v2.3.1) had known memory leak issues when un-mounting animations, potentially leading to performance degradation in single-page applications.fixUpgrade to `lottie-react@2.3.1` or newer to resolve memory leak issues during component unmount.
affects: <2.3.1
gotchaIn versions prior to 2.3.1, the `loop` property might not propagate correctly or accept number types as expected, causing animations to behave unexpectedly.fixUpgrade to `lottie-react@2.3.1` or newer to ensure correct handling of the `loop` property, including number types for specific loop counts.
affects: <2.3.1
Errors
Common errors & fixes
TypeError: (0 , _lottie_react__WEBPACK_IMPORTED_MODULE_2__.default) is not a function
Attempting to import the `Lottie` component as a named export when it is a default export, often seen in webpack-bundled applications.
fixChange your import statement from `import { Lottie } from 'lottie-react';` to `import Lottie from 'lottie-react';`. React hooks can only be called inside the body of a function component.
Using `useLottie` or `useLottieInteractivity` hooks with an incompatible React version (older than 16.8.0) or outside a React functional component.
fixVerify that `react` and `react-dom` versions are `16.8.0` or higher, and ensure hooks are called within a functional component or a custom hook.
Animation plays more than once despite `loop: false` setting, especially when `initialSegment` is not specified.
A bug in `lottie-react` versions prior to 2.3.1 where animations configured with `loop: false` could play at least twice under specific conditions, particularly without `initialSegment`.
fixUpgrade `lottie-react` to version `2.3.1` or higher to resolve this animation playback issue.
Audit
Dependencies
reactrequiredPeer dependency required for all React component/hook libraries.
react-domrequiredPeer dependency required for rendering React components.