0
# Animation Functions
1

2
Declarative animation utilities for creating smooth, performant animations that run on the UI thread. These functions provide the building blocks for all animated transitions in React Native Reanimated.
3

4
## Capabilities
5

6
### Timing-Based Animations
7

8
Creates duration and easing-based animations for smooth transitions.
9

10
```typescript { .api }
11
/**
12
 * Creates a timing-based animation with duration and easing
13
 * @param toValue - Target value to animate to
14
 * @param config - Animation configuration options
15
 * @param callback - Optional callback when animation completes
16
 * @returns Animation object for use with shared values
17
 */
18
function withTiming<T extends AnimatableValue>(
19
  toValue: T,
20
  config?: WithTimingConfig,
21
  callback?: AnimationCallback
22
): T;
23

24
interface WithTimingConfig {
25
  /** Animation duration in milliseconds (default: 300) */
26
  duration?: number;
27
  /** Easing function for animation curve (default: Easing.inOut(Easing.quad)) */
28
  easing?: EasingFunction;
29
  /** Reduce motion behavior for accessibility */
30
  reduceMotion?: ReduceMotion;
31
}
32
```
33

34
**Usage Examples:**
35

36
```typescript
37
import { useSharedValue, withTiming, Easing } from "react-native-reanimated";
38

39
const MyComponent = () => {
40
  const opacity = useSharedValue(0);
41
  const position = useSharedValue({ x: 0, y: 0 });
42

43
  // Basic timing animation
44
  const fadeIn = () => {
45
    opacity.value = withTiming(1, { duration: 500 });
46
  };
47

48
  // Custom easing and callback
49
  const slideUp = () => {
50
    position.value = withTiming(
51
      { x: 0, y: -100 },
52
      {
53
        duration: 800,
54
        easing: Easing.out(Easing.exp),
55
      },
56
      (finished) => {
57
        if (finished) {
58
          console.log("Animation completed");
59
        }
60
      }
61
    );
62
  };
63

64
  // Accessibility-aware animation
65
  const respectMotionPreference = () => {
66
    opacity.value = withTiming(1, {
67
      duration: 300,
68
      reduceMotion: ReduceMotion.System, // Respects system settings
69
    });
70
  };
71

72
  return <Animated.View style={animatedStyle} />;
73
};
74
```
75

76
### Spring-Based Animations
77

78
Creates physics-based spring animations for natural, bouncy movements.
79

80
```typescript { .api }
81
/**
82
 * Creates a spring-based animation with physics simulation
83
 * @param toValue - Target value to animate to
84
 * @param config - Spring configuration options
85
 * @param callback - Optional callback when animation completes
86
 * @returns Animation object for use with shared values
87
 */
88
function withSpring<T extends AnimatableValue>(
89
  toValue: T,
90
  config?: WithSpringConfig,
91
  callback?: AnimationCallback
92
): T;
93

94
interface WithSpringConfig {
95
  /** Spring damping factor (default: 10) */
96
  damping?: number;
97
  /** Spring mass (default: 1) */
98
  mass?: number;
99
  /** Spring stiffness (default: 100) */
100
  stiffness?: number;
101
  /** Prevent spring overshoot (default: false) */
102
  overshootClamping?: boolean;
103
  /** Rest displacement threshold (default: 0.01) */
104
  restDisplacementThreshold?: number;
105
  /** Rest speed threshold (default: 2) */
106
  restSpeedThreshold?: number;
107
  /** Initial velocity */
108
  velocity?: number | { x: number; y: number };
109
  /** Reduce motion behavior for accessibility */
110
  reduceMotion?: ReduceMotion;
111
}
112
```
113

114
**Predefined Spring Configurations:**
115

116
```typescript { .api }
117
/** Gentle, soft spring animation */
118
const GentleSpringConfig: WithSpringConfig;
119
/** Gentle spring with specific duration */
120
const GentleSpringConfigWithDuration: WithSpringConfig;
121
/** Quick, snappy spring animation */
122
const SnappySpringConfig: WithSpringConfig;
123
/** Snappy spring with specific duration */
124
const SnappySpringConfigWithDuration: WithSpringConfig;
125
/** Bouncy, wiggly spring animation */
126
const WigglySpringConfig: WithSpringConfig;
127
/** Wiggly spring with specific duration */
128
const WigglySpringConfigWithDuration: WithSpringConfig;
129
/** Default Reanimated 3 spring configuration */
130
const Reanimated3DefaultSpringConfig: WithSpringConfig;
131
/** Default Reanimated 3 spring with duration */
132
const Reanimated3DefaultSpringConfigWithDuration: WithSpringConfig;
133
```
134

135
**Usage Examples:**
136

137
```typescript
138
import { 
139
  useSharedValue, 
140
  withSpring, 
141
  GentleSpringConfig,
142
  SnappySpringConfig 
143
} from "react-native-reanimated";
144

145
const MyComponent = () => {
146
  const scale = useSharedValue(1);
147
  const rotation = useSharedValue(0);
148

149
  // Basic spring animation
150
  const bounce = () => {
151
    scale.value = withSpring(1.5);
152
  };
153

154
  // Custom spring configuration
155
  const customSpring = () => {
156
    rotation.value = withSpring(180, {
157
      damping: 15,
158
      stiffness: 150,
159
      mass: 1.5,
160
    });
161
  };
162

163
  // Using predefined configurations
164
  const gentleBounce = () => {
165
    scale.value = withSpring(1.2, GentleSpringConfig);
166
  };
167

168
  const snappyAnimation = () => {
169
    scale.value = withSpring(0.8, SnappySpringConfig, (finished) => {
170
      if (finished) {
171
        scale.value = withSpring(1, GentleSpringConfig);
172
      }
173
    });
174
  };
175

176
  // Spring with initial velocity
177
  const flingAnimation = () => {
178
    rotation.value = withSpring(360, {
179
      velocity: 1000, // High initial velocity
180
      damping: 20,
181
    });
182
  };
183

184
  return <Animated.View style={animatedStyle} />;
185
};
186
```
187

188
### Decay Animations
189

190
Creates animations that mimic objects in motion with friction, ideal for scroll momentum.
191

192
```typescript { .api }
193
/**
194
 * Creates a decay animation that slows down over time with friction
195
 * @param config - Decay configuration with velocity and deceleration
196
 * @param callback - Optional callback when animation completes
197
 * @returns Animation object for position values
198
 */
199
function withDecay(
200
  config: WithDecayConfig,
201
  callback?: AnimationCallback
202
): number;
203

204
interface WithDecayConfig {
205
  /** Deceleration rate (default: 0.998) */
206
  deceleration?: number;
207
  /** Initial velocity for the decay */
208
  velocity?: number;
209
  /** Optional bounds to clamp the final value */
210
  clamp?: readonly [number, number];
211
  /** Velocity multiplier factor (default: 1) */
212
  velocityFactor?: number;
213
  /** Rubber band effect when hitting bounds (default: 0) */
214
  rubberBandFactor?: number;
215
}
216
```
217

218
**Usage Examples:**
219

220
```typescript
221
import { useSharedValue, withDecay } from "react-native-reanimated";
222

223
const MyComponent = () => {
224
  const translateX = useSharedValue(0);
225
  const scrollY = useSharedValue(0);
226

227
  // Basic decay animation
228
  const flingHorizontal = (velocity: number) => {
229
    translateX.value = withDecay({
230
      velocity: velocity,
231
      deceleration: 0.995,
232
    });
233
  };
234

235
  // Decay with bounds
236
  const boundedScroll = (velocity: number) => {
237
    scrollY.value = withDecay({
238
      velocity: velocity,
239
      clamp: [0, 1000], // Limit scroll between 0 and 1000
240
      deceleration: 0.998,
241
    });
242
  };
243

244
  // Decay with rubber band effect
245
  const rubberBandDecay = (velocity: number) => {
246
    translateX.value = withDecay({
247
      velocity: velocity,
248
      clamp: [-200, 200],
249
      rubberBandFactor: 0.7, // Bounce back effect
250
    });
251
  };
252

253
  return <Animated.View style={animatedStyle} />;
254
};
255
```
256

257
### Animation Modifiers
258

259
Utilities for composing and modifying animations.
260

261
```typescript { .api }
262
/**
263
 * Adds a delay before starting an animation
264
 * @param delayMs - Delay in milliseconds
265
 * @param delayedAnimation - Animation to execute after delay
266
 * @returns Modified animation with delay
267
 */
268
function withDelay<T>(delayMs: number, delayedAnimation: T): T;
269

270
/**
271
 * Repeats an animation multiple times
272
 * @param animation - Animation to repeat
273
 * @param numberOfReps - Number of repetitions (-1 for infinite)
274
 * @param reverse - Whether to reverse direction on each repeat
275
 * @param callback - Optional callback when all repetitions complete
276
 * @returns Repeated animation
277
 */
278
function withRepeat<T>(
279
  animation: T,
280
  numberOfReps?: number,
281
  reverse?: boolean,
282
  callback?: AnimationCallback
283
): T;
284

285
/**
286
 * Executes animations in sequence
287
 * @param animations - Animations to execute in order
288
 * @returns Sequential animation
289
 */
290
function withSequence<T>(...animations: T[]): T;
291

292
/**
293
 * Clamps animation values within specified bounds
294
 * @param animation - Animation to clamp
295
 * @param min - Minimum allowed value
296
 * @param max - Maximum allowed value
297
 * @returns Clamped animation
298
 */
299
function withClamp<T>(animation: T, min: number, max: number): T;
300
```
301

302
**Usage Examples:**
303

304
```typescript
305
import { 
306
  useSharedValue, 
307
  withTiming, 
308
  withSpring,
309
  withDelay, 
310
  withRepeat, 
311
  withSequence,
312
  withClamp 
313
} from "react-native-reanimated";
314

315
const MyComponent = () => {
316
  const opacity = useSharedValue(1);
317
  const scale = useSharedValue(1);
318
  const rotation = useSharedValue(0);
319

320
  // Delayed animation
321
  const fadeInWithDelay = () => {
322
    opacity.value = withDelay(500, withTiming(1, { duration: 300 }));
323
  };
324

325
  // Repeating animation
326
  const pulse = () => {
327
    scale.value = withRepeat(
328
      withTiming(1.2, { duration: 500 }),
329
      -1, // Infinite repetitions
330
      true // Reverse direction
331
    );
332
  };
333

334
  // Sequential animations
335
  const complexSequence = () => {
336
    opacity.value = withSequence(
337
      withTiming(0, { duration: 200 }),
338
      withDelay(300, withTiming(0.5, { duration: 200 })),
339
      withTiming(1, { duration: 200 })
340
    );
341
  };
342

343
  // Clamped animation
344
  const boundedRotation = () => {
345
    rotation.value = withClamp(
346
      withSpring(360),
347
      0,   // Min rotation
348
      180  // Max rotation
349
    );
350
  };
351

352
  // Complex combination
353
  const showWithFlourish = () => {
354
    // Fade in with delay
355
    opacity.value = withDelay(200, withTiming(1));
356
    
357
    // Scale up, then settle
358
    scale.value = withSequence(
359
      withSpring(1.3, SnappySpringConfig),
360
      withSpring(1, GentleSpringConfig)
361
    );
362
    
363
    // Rotate with repeating wiggle
364
    rotation.value = withRepeat(
365
      withSequence(
366
        withTiming(5, { duration: 100 }),
367
        withTiming(-5, { duration: 100 }),
368
        withTiming(0, { duration: 100 })
369
      ),
370
      3, // 3 times
371
      false
372
    );
373
  };
374

375
  return <Animated.View style={animatedStyle} />;
376
};
377
```
378

379
### Animation Control
380

381
Functions for controlling and managing running animations.
382

383
```typescript { .api }
384
/**
385
 * Cancels any running animation on a shared value
386
 * @param sharedValue - SharedValue to cancel animations on
387
 */
388
function cancelAnimation(sharedValue: SharedValue<any>): void;
389

390
/**
391
 * Defines a custom animation with factory function
392
 * @param starting - Starting configuration or value
393
 * @param factory - Function that creates the animation
394
 * @returns Custom animation object
395
 */
396
function defineAnimation<T>(starting: any, factory: () => T): T;
397
```
398

399
**Usage Examples:**
400

401
```typescript
402
import { useSharedValue, withTiming, cancelAnimation } from "react-native-reanimated";
403

404
const MyComponent = () => {
405
  const progress = useSharedValue(0);
406

407
  const startLongAnimation = () => {
408
    progress.value = withTiming(1, { duration: 5000 });
409
  };
410

411
  const stopAnimation = () => {
412
    cancelAnimation(progress);
413
  };
414

415
  // Custom animation example
416
  const customBounce = defineAnimation(0, () => {
417
    'worklet';
418
    return (targetValue: number) => {
419
      'worklet';
420
      return {
421
        animation: (timestamp: number, current: number) => {
422
          // Custom animation logic
423
          const progress = Math.min((timestamp - startTime) / 1000, 1);
424
          const bounceValue = Math.sin(progress * Math.PI * 3) * (1 - progress);
425
          return current + (targetValue - current) * progress + bounceValue * 50;
426
        },
427
        finished: false,
428
      };
429
    };
430
  });
431

432
  return (
433
    <View>
434
      <Button title="Start Animation" onPress={startLongAnimation} />
435
      <Button title="Stop Animation" onPress={stopAnimation} />
436
    </View>
437
  );
438
};
439
```
440

441
## Type Definitions
442

443
```typescript { .api }
444
type AnimatableValue = number | string | number[];
445

446
interface AnimationCallback {
447
  (finished?: boolean, current?: AnimatableValue): void;
448
}
449

450
interface AnimationObject {
451
  __reanimatedWorklet?: boolean;
452
  callback?: AnimationCallback;
453
  current?: AnimatableValue;
454
  finished?: boolean;
455
  cancelled?: boolean;
456
  reduceMotion?: ReduceMotion;
457
}
458

459
enum ReduceMotion {
460
  System = "system",
461
  Always = "always", 
462
  Never = "never"
463
}
464

465
type EasingFunction = (value: number) => number;
466

467
interface EasingFunctionFactory {
468
  factory: () => EasingFunction;
469
}
470

471
type TimingAnimation = AnimationObject & {
472
  type: "timing";
473
  toValue: AnimatableValue;
474
  startTime: number;
475
  config: WithTimingConfig;
476
};
477

478
type SpringAnimation = AnimationObject & {
479
  type: "spring";
480
  toValue: AnimatableValue;
481
  startTime: number;
482
  config: WithSpringConfig;
483
};
484

485
type DecayAnimation = AnimationObject & {
486
  type: "decay";
487
  config: WithDecayConfig;
488
  velocity: number;
489
};
490

491
type DelayAnimation = AnimationObject & {
492
  type: "delay";
493
  delayMs: number;
494
  animation: AnimationObject;
495
};
496

497
type RepeatAnimation = AnimationObject & {
498
  type: "repeat";
499
  animation: AnimationObject;
500
  numberOfReps: number;
501
  reverse: boolean;
502
};
503

504
type SequenceAnimation = AnimationObject & {
505
  type: "sequence";
506
  animations: AnimationObject[];
507
};
508
```