0
# Hook API
1

2
Hook-based API providing programmatic control over Lottie animations with method returns for play, pause, stop, and other animation controls.
3

4
## Capabilities
5

6
### useLottie Hook
7

8
Core hook for managing Lottie animations with programmatic control, returning a View component and animation control methods.
9

10
```typescript { .api }
11
/**
12
 * Hook for managing Lottie animations with programmatic control
13
 * @param props - Lottie configuration options
14
 * @param style - Optional CSS styles for the animation container
15
 * @returns Object containing View component and control methods
16
 */
17
function useLottie<T extends RendererType = "svg">(
18
  props: LottieOptions<T>,
19
  style?: CSSProperties
20
): { View: ReactElement } & LottieRefCurrentProps;
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import React from "react";
27
import { useLottie } from "lottie-react";
28
import animationData from "./animation.json";
29

30
// Basic hook usage
31
const BasicHookAnimation = () => {
32
  const { View } = useLottie({
33
    animationData,
34
    loop: true,
35
    autoplay: true,
36
  });
37

38
  return <div>{View}</div>;
39
};
40

41
// With programmatic controls
42
const ControlledAnimation = () => {
43
  const { View, play, pause, stop, setSpeed } = useLottie({
44
    animationData,
45
    loop: true,
46
    autoplay: false,
47
  });
48

49
  return (
50
    <div>
51
      <div style={{ marginBottom: 20 }}>{View}</div>
52
      <div>
53
        <button onClick={play}>Play</button>
54
        <button onClick={pause}>Pause</button>
55
        <button onClick={stop}>Stop</button>
56
        <button onClick={() => setSpeed(2)}>2x Speed</button>
57
        <button onClick={() => setSpeed(0.5)}>0.5x Speed</button>
58
      </div>
59
    </div>
60
  );
61
};
62

63
// With custom styling
64
const StyledHookAnimation = () => {
65
  const { View, animationLoaded } = useLottie(
66
    {
67
      animationData,
68
      loop: false,
69
      autoplay: true,
70
    },
71
    { 
72
      width: 300, 
73
      height: 300, 
74
      border: "1px solid #ccc",
75
      borderRadius: "8px"
76
    }
77
  );
78

79
  return (
80
    <div>
81
      {!animationLoaded && <div>Loading animation...</div>}
82
      {View}
83
    </div>
84
  );
85
};
86

87
// With advanced controls
88
const AdvancedControls = () => {
89
  const { 
90
    View, 
91
    play, 
92
    pause, 
93
    goToAndStop, 
94
    goToAndPlay, 
95
    playSegments,
96
    getDuration,
97
    setDirection 
98
  } = useLottie({
99
    animationData,
100
    loop: false,
101
    autoplay: false,
102
  });
103

104
  const handleGoToFrame = (frame: number) => {
105
    goToAndStop(frame, true);
106
  };
107

108
  const handlePlaySegment = () => {
109
    playSegments([10, 50], true);
110
  };
111

112
  const handleReverse = () => {
113
    setDirection(-1);
114
    play();
115
  };
116

117
  return (
118
    <div>
119
      {View}
120
      <div>
121
        <button onClick={() => handleGoToFrame(0)}>Go to Start</button>
122
        <button onClick={() => handleGoToFrame(25)}>Go to Middle</button>
123
        <button onClick={handlePlaySegment}>Play Segment 10-50</button>
124
        <button onClick={handleReverse}>Play Reverse</button>
125
        <p>Duration: {getDuration()} seconds</p>
126
      </div>
127
    </div>
128
  );
129
};
130

131
// With event handling
132
const EventHandledAnimation = () => {
133
  const { View } = useLottie({
134
    animationData,
135
    loop: true,
136
    autoplay: true,
137
    onComplete: () => console.log("Animation completed"),
138
    onLoopComplete: () => console.log("Loop completed"),
139
    onEnterFrame: (event) => console.log("Current frame:", event.currentTime),
140
  });
141

142
  return View;
143
};
144
```
145

146
### Hook Return Value
147

148
The useLottie hook returns an object containing the View component and all animation control methods.
149

150
```typescript { .api }
151
interface UseLottieReturn extends LottieRefCurrentProps {
152
  /** React element containing the Lottie animation */
153
  View: ReactElement;
154
}
155

156
interface LottieRefCurrentProps {
157
  /** Start/resume animation playback */
158
  play: () => void;
159
  /** Stop animation and reset to beginning */
160
  stop: () => void;
161
  /** Pause animation at current frame */
162
  pause: () => void;
163
  /** Set animation playback speed (1 = normal, 2 = double speed, 0.5 = half speed) */
164
  setSpeed: (speed: number) => void;
165
  /** Go to specific frame or time and stop there */
166
  goToAndStop: (value: number, isFrame?: boolean) => void;
167
  /** Go to specific frame or time and start playing from there */
168
  goToAndPlay: (value: number, isFrame?: boolean) => void;
169
  /** Set animation direction (1 = forward, -1 = reverse) */
170
  setDirection: (direction: AnimationDirection) => void;
171
  /** Play specific segments of the animation */
172
  playSegments: (segments: AnimationSegment | AnimationSegment[], forceFlag?: boolean) => void;
173
  /** Enable/disable subframe rendering for smoother animation */
174
  setSubframe: (useSubFrames: boolean) => void;
175
  /** Get animation duration in seconds (default) or frames */
176
  getDuration: (inFrames?: boolean) => number | undefined;
177
  /** Destroy animation instance and clean up resources */
178
  destroy: () => void;
179
  /** Ref to the animation container DOM element */
180
  animationContainerRef: RefObject<HTMLDivElement>;
181
  /** Whether animation data has been loaded and is ready */
182
  animationLoaded: boolean;
183
  /** Direct access to the underlying lottie-web AnimationItem */
184
  animationItem: AnimationItem | undefined;
185
}
186
```
187

188
### Hook Parameters
189

190
Configuration options for the useLottie hook.
191

192
```typescript { .api }
193
interface LottieOptions<T extends RendererType = "svg"> extends 
194
  Omit<AnimationConfigWithData<T>, "container" | "animationData">, 
195
  Omit<React.HTMLProps<HTMLDivElement>, "loop"> {
196
  /** Animation data object (required) - JSON exported from After Effects */
197
  animationData: unknown;
198
  /** Optional ref for external access to animation controls */
199
  lottieRef?: LottieRef;
200
  /** Whether to loop the animation (default: false) */
201
  loop?: boolean;
202
  /** Whether to start playing automatically (default: true) */
203
  autoplay?: boolean;
204
  /** Animation renderer: "svg" (default), "canvas", or "html" */
205
  renderer?: T;
206
  /** Animation name for debugging purposes */
207
  name?: string;
208
  /** Base path for loading animation assets */
209
  assetsPath?: string;
210
  /** Initial segment to play [startFrame, endFrame] */
211
  initialSegment?: AnimationSegment;
212
  /** Renderer-specific configuration options */
213
  rendererSettings?: any;
214
  
215
  // Event handlers - all optional
216
  /** Called when animation completes (non-looping animations) */
217
  onComplete?: AnimationEventCallback | null;
218
  /** Called when each loop completes (looping animations) */
219
  onLoopComplete?: AnimationEventCallback | null;
220
  /** Called on each animation frame - use sparingly for performance */
221
  onEnterFrame?: AnimationEventCallback | null;
222
  /** Called when animation segment starts playing */
223
  onSegmentStart?: AnimationEventCallback | null;
224
  /** Called when animation configuration is ready */
225
  onConfigReady?: AnimationEventCallback | null;
226
  /** Called when animation data is loaded and ready */
227
  onDataReady?: AnimationEventCallback | null;
228
  /** Called if animation data fails to load */
229
  onDataFailed?: AnimationEventCallback | null;
230
  /** Called when all images in animation are loaded */
231
  onLoadedImages?: AnimationEventCallback | null;
232
  /** Called when DOM elements are loaded */
233
  onDOMLoaded?: AnimationEventCallback | null;
234
  /** Called when animation instance is destroyed */
235
  onDestroy?: AnimationEventCallback | null;
236
}
237
```
238

239
### Animation Control Methods
240

241
Detailed descriptions of all animation control methods returned by the hook.
242

243
```typescript { .api }
244
/**
245
 * Start or resume animation playback from current position
246
 */
247
play: () => void;
248

249
/**
250
 * Stop animation and reset playhead to beginning
251
 */
252
stop: () => void;
253

254
/**
255
 * Pause animation at current position
256
 */
257
pause: () => void;
258

259
/**
260
 * Set animation playback speed
261
 * @param speed - Playback speed multiplier (1 = normal, 2 = double, 0.5 = half)
262
 */
263
setSpeed: (speed: number) => void;
264

265
/**
266
 * Jump to specific frame or time and stop there
267
 * @param value - Frame number or time in seconds
268
 * @param isFrame - Whether value is frame number (true) or seconds (false)
269
 */
270
goToAndStop: (value: number, isFrame?: boolean) => void;
271

272
/**
273
 * Jump to specific frame or time and start playing from there
274
 * @param value - Frame number or time in seconds  
275
 * @param isFrame - Whether value is frame number (true) or seconds (false)
276
 */
277
goToAndPlay: (value: number, isFrame?: boolean) => void;
278

279
/**
280
 * Set animation playback direction
281
 * @param direction - 1 for forward, -1 for reverse
282
 */
283
setDirection: (direction: AnimationDirection) => void;
284

285
/**
286
 * Play specific segments of the animation
287
 * @param segments - Single segment [start, end] or array of segments
288
 * @param forceFlag - Whether to force immediate segment playback
289
 */
290
playSegments: (
291
  segments: AnimationSegment | AnimationSegment[], 
292
  forceFlag?: boolean
293
) => void;
294

295
/**
296
 * Enable or disable subframe rendering for smoother animation
297
 * @param useSubFrames - Whether to use subframe rendering
298
 */
299
setSubframe: (useSubFrames: boolean) => void;
300

301
/**
302
 * Get the total duration of the animation
303
 * @param inFrames - Return duration in frames (true) or seconds (false)
304
 * @returns Duration value or undefined if not loaded
305
 */
306
getDuration: (inFrames?: boolean) => number | undefined;
307

308
/**
309
 * Destroy the animation instance and clean up all resources
310
 * Should be called when component unmounts or animation is no longer needed
311
 */
312
destroy: () => void;
313
```
314

315
## Types
316

317
```typescript { .api }
318
type RendererType = "svg" | "canvas" | "html";
319
type AnimationDirection = 1 | -1;
320
type AnimationSegment = [number, number];
321
type AnimationEventCallback<T = any> = (event: T) => void;
322
type LottieRef = MutableRefObject<LottieRefCurrentProps | null>;
323

324
interface AnimationItem {
325
  // Core lottie-web AnimationItem interface
326
  play(): void;
327
  stop(): void;
328
  pause(): void;
329
  destroy(): void;
330
  setSpeed(speed: number): void;
331
  goToAndStop(value: number, isFrame?: boolean): void;
332
  goToAndPlay(value: number, isFrame?: boolean): void;
333
  setDirection(direction: AnimationDirection): void;
334
  playSegments(segments: AnimationSegment | AnimationSegment[], forceFlag?: boolean): void;
335
  getDuration(inFrames?: boolean): number;
336
  // ... additional lottie-web properties
337
}
338
```