0
# Lottie React
1
2
Lottie React is a React wrapper for Lottie animations that provides both declarative Component and Hook-based APIs. It wraps the lottie-web library to enable seamless integration of Adobe After Effects animations in React applications with full control over playback, styling, and interactivity.
3
4
## Package Information
5
6
- **Package Name**: lottie-react
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install lottie-react`
10
11
## Core Imports
12
13
```typescript
14
import Lottie from "lottie-react";
15
import { useLottie, useLottieInteractivity, LottiePlayer } from "lottie-react";
16
17
// Type imports
18
import type {
19
LottieOptions,
20
LottieComponentProps,
21
LottieRefCurrentProps,
22
InteractivityProps,
23
Action
24
} from "lottie-react";
25
```
26
27
For CommonJS:
28
29
```javascript
30
const Lottie = require("lottie-react").default;
31
const { useLottie, useLottieInteractivity, LottiePlayer } = require("lottie-react");
32
```
33
34
## Basic Usage
35
36
```typescript
37
import React from "react";
38
import Lottie from "lottie-react";
39
import animationData from "./animation.json";
40
41
// Basic component usage
42
const AnimationComponent = () => (
43
<Lottie
44
animationData={animationData}
45
loop={true}
46
autoplay={true}
47
style={{ width: 300, height: 300 }}
48
/>
49
);
50
51
// Hook-based usage for programmatic control
52
import { useLottie } from "lottie-react";
53
54
const HookBasedAnimation = () => {
55
const { View, play, pause, stop } = useLottie({
56
animationData,
57
loop: true,
58
autoplay: false,
59
});
60
61
return (
62
<div>
63
{View}
64
<button onClick={play}>Play</button>
65
<button onClick={pause}>Pause</button>
66
<button onClick={stop}>Stop</button>
67
</div>
68
);
69
};
70
```
71
72
## Architecture
73
74
Lottie React is built around several key components:
75
76
- **Declarative Component API**: Main `Lottie` component for simple use cases with props-based configuration
77
- **Hook-based API**: `useLottie` hook providing programmatic control and React element output
78
- **Interactivity System**: `useLottieInteractivity` for scroll and cursor-based animation control
79
- **Type Safety**: Full TypeScript support with comprehensive type definitions
80
- **lottie-web Integration**: Direct re-export of lottie-web's `LottiePlayer` for advanced use cases
81
82
## Capabilities
83
84
### Component API
85
86
Declarative React component for rendering Lottie animations with simple props-based configuration and optional interactivity features.
87
88
```typescript { .api }
89
export default function Lottie(props: LottieComponentProps): ReactElement;
90
91
interface LottieComponentProps extends LottieOptions {
92
interactivity?: Omit<InteractivityProps, "lottieObj">;
93
}
94
```
95
96
[Component API](./component-api.md)
97
98
### Hook API
99
100
Hook-based API providing programmatic control over Lottie animations with method returns for play, pause, stop, and other animation controls.
101
102
```typescript { .api }
103
function useLottie<T extends RendererType = "svg">(
104
props: LottieOptions<T>,
105
style?: CSSProperties
106
): { View: ReactElement } & LottieRefCurrentProps;
107
```
108
109
[Hook API](./hook-api.md)
110
111
### Interactivity API
112
113
Advanced interactivity system for creating scroll-triggered and cursor-responsive Lottie animations with configurable actions and behaviors.
114
115
```typescript { .api }
116
function useLottieInteractivity(props: InteractivityProps): ReactElement;
117
118
interface InteractivityProps {
119
lottieObj: { View: ReactElement } & LottieRefCurrentProps;
120
actions: Action[];
121
mode: "scroll" | "cursor";
122
}
123
```
124
125
[Interactivity API](./interactivity-api.md)
126
127
### LottiePlayer Access
128
129
Direct access to the lottie-web player for advanced use cases requiring low-level animation control.
130
131
```typescript { .api }
132
import { LottiePlayer } from "lottie-react";
133
// LottiePlayer is the lottie-web library re-exported for direct access
134
```
135
136
## Core Types
137
138
```typescript { .api }
139
interface LottieOptions<T extends RendererType = "svg"> extends
140
Omit<AnimationConfigWithData<T>, "container" | "animationData">,
141
Omit<React.HTMLProps<HTMLDivElement>, "loop"> {
142
animationData: unknown;
143
lottieRef?: LottieRef;
144
onComplete?: AnimationEventCallback | null;
145
onLoopComplete?: AnimationEventCallback | null;
146
onEnterFrame?: AnimationEventCallback | null;
147
onSegmentStart?: AnimationEventCallback | null;
148
onConfigReady?: AnimationEventCallback | null;
149
onDataReady?: AnimationEventCallback | null;
150
onDataFailed?: AnimationEventCallback | null;
151
onLoadedImages?: AnimationEventCallback | null;
152
onDOMLoaded?: AnimationEventCallback | null;
153
onDestroy?: AnimationEventCallback | null;
154
}
155
156
interface LottieRefCurrentProps {
157
play: () => void;
158
stop: () => void;
159
pause: () => void;
160
setSpeed: (speed: number) => void;
161
goToAndStop: (value: number, isFrame?: boolean) => void;
162
goToAndPlay: (value: number, isFrame?: boolean) => void;
163
setDirection: (direction: AnimationDirection) => void;
164
playSegments: (segments: AnimationSegment | AnimationSegment[], forceFlag?: boolean) => void;
165
setSubframe: (useSubFrames: boolean) => void;
166
getDuration: (inFrames?: boolean) => number | undefined;
167
destroy: () => void;
168
animationContainerRef: RefObject<HTMLDivElement>;
169
animationLoaded: boolean;
170
animationItem: AnimationItem | undefined;
171
}
172
173
type LottieRef = MutableRefObject<LottieRefCurrentProps | null>;
174
175
interface PartialLottieOptions extends Omit<LottieOptions, "animationData"> {
176
animationData?: LottieOptions["animationData"];
177
}
178
179
interface PartialLottieComponentProps extends Omit<LottieComponentProps, "animationData"> {
180
animationData?: LottieOptions["animationData"];
181
}
182
183
// Re-exported from lottie-web
184
type RendererType = "svg" | "canvas" | "html";
185
type AnimationDirection = 1 | -1;
186
type AnimationSegment = [number, number];
187
```