0
# Component API
1

2
Declarative React component for rendering Lottie animations with simple props-based configuration and optional interactivity features.
3

4
## Capabilities
5

6
### Lottie Component
7

8
Main React component for rendering Lottie animations declaratively using props.
9

10
```typescript { .api }
11
/**
12
 * Main Lottie React component for declarative animation rendering
13
 * @param props - Component props including animation data and options
14
 * @returns React element with Lottie animation
15
 */
16
export default function Lottie(props: LottieComponentProps): ReactElement;
17

18
interface LottieComponentProps extends LottieOptions {
19
  /** Optional interactivity configuration for scroll/cursor interactions */
20
  interactivity?: Omit<InteractivityProps, "lottieObj">;
21
}
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import React from "react";
28
import Lottie from "lottie-react";
29
import animationData from "./animation.json";
30

31
// Basic usage
32
const BasicAnimation = () => (
33
  <Lottie 
34
    animationData={animationData}
35
    loop={true}
36
    autoplay={true}
37
  />
38
);
39

40
// With styling and HTML props
41
const StyledAnimation = () => (
42
  <Lottie
43
    animationData={animationData}
44
    loop={false}
45
    autoplay={true}
46
    style={{ width: 400, height: 400 }}
47
    className="my-animation"
48
    data-testid="lottie-animation"
49
  />
50
);
51

52
// With ref for imperative access
53
import { useRef } from "react";
54

55
const AnimationWithRef = () => {
56
  const lottieRef = useRef(null);
57

58
  const handlePlay = () => {
59
    lottieRef.current?.play();
60
  };
61

62
  return (
63
    <div>
64
      <Lottie
65
        lottieRef={lottieRef}
66
        animationData={animationData}
67
        loop={true}
68
        autoplay={false}
69
      />
70
      <button onClick={handlePlay}>Play Animation</button>
71
    </div>
72
  );
73
};
74

75
// With event handlers
76
const AnimationWithEvents = () => (
77
  <Lottie
78
    animationData={animationData}
79
    loop={true}
80
    onComplete={() => console.log("Animation completed")}
81
    onLoopComplete={() => console.log("Loop completed")}
82
    onDataReady={() => console.log("Data ready")}
83
  />
84
);
85

86
// With interactivity
87
const InteractiveAnimation = () => (
88
  <Lottie
89
    animationData={animationData}
90
    loop={false}
91
    autoplay={false}
92
    interactivity={{
93
      mode: "scroll",
94
      actions: [
95
        {
96
          type: "seek",
97
          frames: [0, 100],
98
          visibility: [0, 1.0]
99
        }
100
      ]
101
    }}
102
  />
103
);
104
```
105

106
### Component Props
107

108
All props accepted by the Lottie component, extending LottieOptions with interactivity support.
109

110
```typescript { .api }
111
interface LottieComponentProps extends LottieOptions {
112
  /** Optional interactivity configuration for scroll/cursor interactions */
113
  interactivity?: {
114
    /** Interaction mode: scroll-based or cursor-based */
115
    mode: "scroll" | "cursor";
116
    /** Array of actions to perform based on interactions */
117
    actions: Action[];
118
  };
119
}
120

121
interface LottieOptions<T extends RendererType = "svg"> extends 
122
  Omit<AnimationConfigWithData<T>, "container" | "animationData">, 
123
  Omit<React.HTMLProps<HTMLDivElement>, "loop"> {
124
  /** Animation data object (required) */
125
  animationData: unknown;
126
  /** Optional ref for imperative access to animation controls */
127
  lottieRef?: LottieRef;
128
  /** Whether to loop the animation */
129
  loop?: boolean;
130
  /** Whether to autoplay the animation */
131
  autoplay?: boolean;
132
  /** Animation renderer type */
133
  renderer?: T;
134
  /** Animation name for debugging */
135
  name?: string;
136
  /** Path to animation assets */
137
  assetsPath?: string;
138
  /** Initial segment to play */
139
  initialSegment?: AnimationSegment;
140
  /** Renderer-specific settings */
141
  rendererSettings?: any;
142
  
143
  // Event handlers
144
  /** Called when animation completes */
145
  onComplete?: AnimationEventCallback | null;
146
  /** Called when animation loop completes */
147
  onLoopComplete?: AnimationEventCallback | null;
148
  /** Called on each frame */
149
  onEnterFrame?: AnimationEventCallback | null;
150
  /** Called when animation segment starts */
151
  onSegmentStart?: AnimationEventCallback | null;
152
  /** Called when config is ready */
153
  onConfigReady?: AnimationEventCallback | null;
154
  /** Called when data is ready */
155
  onDataReady?: AnimationEventCallback | null;
156
  /** Called when data loading fails */
157
  onDataFailed?: AnimationEventCallback | null;
158
  /** Called when images are loaded */
159
  onLoadedImages?: AnimationEventCallback | null;
160
  /** Called when DOM is loaded */
161
  onDOMLoaded?: AnimationEventCallback | null;
162
  /** Called when animation is destroyed */
163
  onDestroy?: AnimationEventCallback | null;
164
}
165
```
166

167
### Imperative Access via Ref
168

169
Access animation control methods imperatively using a ref.
170

171
```typescript { .api }
172
interface LottieRefCurrentProps {
173
  /** Start/resume animation playback */
174
  play: () => void;
175
  /** Stop animation and reset to beginning */
176
  stop: () => void;
177
  /** Pause animation at current frame */
178
  pause: () => void;
179
  /** Set animation playback speed */
180
  setSpeed: (speed: number) => void;
181
  /** Go to specific frame/time and stop */
182
  goToAndStop: (value: number, isFrame?: boolean) => void;
183
  /** Go to specific frame/time and play */
184
  goToAndPlay: (value: number, isFrame?: boolean) => void;
185
  /** Set animation direction (1 = forward, -1 = reverse) */
186
  setDirection: (direction: AnimationDirection) => void;
187
  /** Play specific segments of the animation */
188
  playSegments: (segments: AnimationSegment | AnimationSegment[], forceFlag?: boolean) => void;
189
  /** Enable/disable subframe rendering */
190
  setSubframe: (useSubFrames: boolean) => void;
191
  /** Get animation duration in seconds or frames */
192
  getDuration: (inFrames?: boolean) => number | undefined;
193
  /** Destroy animation instance and clean up */
194
  destroy: () => void;
195
  /** Ref to the animation container DOM element */
196
  animationContainerRef: RefObject<HTMLDivElement>;
197
  /** Whether animation data has been loaded */
198
  animationLoaded: boolean;
199
  /** Direct access to lottie-web AnimationItem instance */
200
  animationItem: AnimationItem | undefined;
201
}
202

203
type LottieRef = MutableRefObject<LottieRefCurrentProps | null>;
204
```
205

206
## Types
207

208
```typescript { .api }
209
// Re-exported from lottie-web
210
type RendererType = "svg" | "canvas" | "html";
211
type AnimationDirection = 1 | -1;
212
type AnimationSegment = [number, number];
213
type AnimationEventCallback<T = any> = (event: T) => void;
214

215
interface AnimationConfigWithData<T extends RendererType> {
216
  renderer?: T;
217
  loop?: boolean;
218
  autoplay?: boolean;
219
  name?: string;
220
  assetsPath?: string;
221
  rendererSettings?: any;
222
  // ... other lottie-web config options
223
}
224

225
interface AnimationItem {
226
  play(): void;
227
  stop(): void;
228
  pause(): void;
229
  setSpeed(speed: number): void;
230
  goToAndStop(value: number, isFrame?: boolean): void;
231
  goToAndPlay(value: number, isFrame?: boolean): void;
232
  setDirection(direction: AnimationDirection): void;
233
  playSegments(segments: AnimationSegment | AnimationSegment[], forceFlag?: boolean): void;
234
  setSubframe(useSubFrames: boolean): void;
235
  getDuration(inFrames?: boolean): number;
236
  destroy(): void;
237
  // ... other lottie-web AnimationItem properties
238
}
239
```