0
# Interactivity API
1

2
Advanced interactivity system for creating scroll-triggered and cursor-responsive Lottie animations with configurable actions and behaviors.
3

4
## Capabilities
5

6
### useLottieInteractivity Hook
7

8
Hook for adding scroll-based or cursor-based interactivity to Lottie animations, allowing animations to respond to user interactions.
9

10
```typescript { .api }
11
/**
12
 * Hook for adding interactivity to Lottie animations
13
 * @param props - Interactivity configuration including lottie object, actions, and mode
14
 * @returns React element with interactivity applied
15
 */
16
function useLottieInteractivity(props: InteractivityProps): ReactElement;
17

18
interface InteractivityProps {
19
  /** Lottie object with View component and control methods */
20
  lottieObj: { View: ReactElement } & LottieRefCurrentProps;
21
  /** Array of actions to perform based on interactions */
22
  actions: Action[];
23
  /** Interaction mode: scroll-based or cursor-based */
24
  mode: "scroll" | "cursor";
25
}
26
```
27

28
**Usage Examples:**
29

30
```typescript
31
import React from "react";
32
import { useLottie, useLottieInteractivity } from "lottie-react";
33
import animationData from "./animation.json";
34

35
// Scroll-based interactivity
36
const ScrollAnimation = () => {
37
  const lottieObj = useLottie({
38
    animationData,
39
    loop: false,
40
    autoplay: false,
41
  });
42

43
  const Animation = useLottieInteractivity({
44
    lottieObj,
45
    mode: "scroll",
46
    actions: [
47
      {
48
        type: "seek",
49
        frames: [0, 100],
50
        visibility: [0, 1] // Animate from 0% to 100% visibility
51
      }
52
    ]
53
  });
54

55
  return <div style={{ height: "200vh" }}>{Animation}</div>;
56
};
57

58
// Cursor-based interactivity
59
const CursorAnimation = () => {
60
  const lottieObj = useLottie({
61
    animationData,
62
    loop: false,
63
    autoplay: false,
64
  });
65

66
  const Animation = useLottieInteractivity({
67
    lottieObj,
68
    mode: "cursor",
69
    actions: [
70
      {
71
        type: "seek",
72
        frames: [0, 50],
73
        position: { x: [0, 1], y: [0, 1] }
74
      }
75
    ]
76
  });
77

78
  return (
79
    <div style={{ width: 400, height: 400, border: "1px solid #ccc" }}>
80
      {Animation}
81
    </div>
82
  );
83
};
84

85
// Multiple scroll actions
86
const MultiActionScroll = () => {
87
  const lottieObj = useLottie({
88
    animationData,
89
    loop: false,
90
    autoplay: false,
91
  });
92

93
  const Animation = useLottieInteractivity({
94
    lottieObj,
95
    mode: "scroll",
96
    actions: [
97
      {
98
        type: "play",
99
        frames: [0, 30],
100
        visibility: [0, 0.3]
101
      },
102
      {
103
        type: "seek",  
104
        frames: [30, 60],
105
        visibility: [0.3, 0.7]
106
      },
107
      {
108
        type: "loop",
109
        frames: [60, 90],
110
        visibility: [0.7, 1.0]
111
      }
112
    ]
113
  });
114

115
  return <div style={{ height: "300vh" }}>{Animation}</div>;
116
};
117

118
// Using with main Lottie component
119
import Lottie from "lottie-react";
120

121
const ComponentWithInteractivity = () => (
122
  <div style={{ height: "200vh" }}>
123
    <Lottie
124
      animationData={animationData}
125
      loop={false}
126
      autoplay={false}
127
      interactivity={{
128
        mode: "scroll",
129
        actions: [
130
          {
131
            type: "seek",
132
            frames: [0, 100],
133
            visibility: [0, 1]
134
          }
135
        ]
136
      }}
137
    />
138
  </div>
139
);
140
```
141

142
### Action Types
143

144
Different types of actions that can be triggered by user interactions.
145

146
```typescript { .api }
147
interface Action {
148
  /** Type of action to perform */
149
  type: "seek" | "play" | "stop" | "loop";
150
  /** Frame range for the action [startFrame, endFrame] */
151
  frames: [number] | [number, number];
152
  /** Visibility range for scroll mode [0-1, 0-1] (optional) */
153
  visibility?: [number, number];
154
  /** Position range for cursor mode (optional) */
155
  position?: Position;
156
}
157

158
interface Position {
159
  /** X-axis position range or exact position */
160
  x: number | [number, number];
161
  /** Y-axis position range or exact position */
162
  y: number | [number, number];
163
}
164
```
165

166
**Action Type Details:**
167

168
- **seek**: Scrub through animation frames based on scroll position or cursor location
169
- **play**: Start playing animation when conditions are met
170
- **stop**: Stop animation at specific frame when conditions are met  
171
- **loop**: Loop specific frame range when conditions are met
172

173
### Scroll Mode
174

175
Scroll-based interactivity where animations respond to page scroll position and element visibility.
176

177
```typescript { .api }
178
// Scroll mode actions use visibility ranges
179
interface ScrollAction extends Action {
180
  /** Visibility percentage range [0-1, 0-1] where action is active */
181
  visibility: [number, number];
182
}
183
```
184

185
**Scroll Mode Examples:**
186

187
```typescript
188
// Seek animation based on scroll position
189
{
190
  type: "seek",
191
  frames: [0, 120], // Animation frames 0-120
192
  visibility: [0, 1] // From 0% to 100% element visibility
193
}
194

195
// Play animation when element becomes 50% visible
196
{
197
  type: "play", 
198
  frames: [0, 60],
199
  visibility: [0.5, 1.0]
200
}
201

202
// Loop specific frames when element is fully visible
203
{
204
  type: "loop",
205
  frames: [60, 90],
206
  visibility: [0.8, 1.0]
207
}
208

209
// Stop at specific frame when scrolling up
210
{
211
  type: "stop",
212
  frames: [30],
213
  visibility: [0, 0.3]
214
}
215
```
216

217
### Cursor Mode
218

219
Cursor-based interactivity where animations respond to mouse position within the animation container.
220

221
```typescript { .api }
222
// Cursor mode actions use position ranges
223
interface CursorAction extends Action {
224
  /** Position ranges where action is active */
225
  position: Position;
226
}
227

228
interface Position {
229
  /** X-axis: exact position (number) or range ([min, max]) in 0-1 coordinates */
230
  x: number | [number, number];
231
  /** Y-axis: exact position (number) or range ([min, max]) in 0-1 coordinates */
232
  y: number | [number, number];
233
}
234
```
235

236
**Cursor Mode Examples:**
237

238
```typescript
239
// Seek animation based on cursor position across entire container
240
{
241
  type: "seek",
242
  frames: [0, 100],
243
  position: { x: [0, 1], y: [0, 1] }
244
}
245

246
// Play animation in top-left quadrant
247
{
248
  type: "play",
249
  frames: [0, 50], 
250
  position: { x: [0, 0.5], y: [0, 0.5] }
251
}
252

253
// Loop animation when cursor is in center
254
{
255
  type: "loop",
256
  frames: [25, 75],
257
  position: { x: 0.5, y: 0.5 }
258
}
259

260
// Stop animation in bottom area
261
{
262
  type: "stop", 
263
  frames: [0],
264
  position: { x: [0, 1], y: [0.7, 1] }
265
}
266
```
267

268

269
## Types
270

271
```typescript { .api }
272
type InteractivityMode = "scroll" | "cursor";
273
type ActionType = "seek" | "play" | "stop" | "loop";
274
type Axis = "x" | "y";
275

276
interface InteractivityProps {
277
  lottieObj: { View: ReactElement } & LottieRefCurrentProps;
278
  actions: Action[];
279
  mode: InteractivityMode;
280
}
281

282
interface Action {
283
  type: ActionType;
284
  frames: [number] | [number, number];
285
  visibility?: [number, number];
286
  position?: Position;
287
}
288

289
interface Position {
290
  [key in Axis]: number | [number, number];
291
}
292
```