0
# React Native Reanimated
1

2
React Native Reanimated is a comprehensive animation library that provides a more powerful and performant alternative to React Native's built-in Animated library. It enables developers to create smooth, complex animations that run on the UI thread for optimal performance, utilizing a declarative API with animated values, worklets, and gesture handling.
3

4
## Package Information
5

6
- **Package Name**: react-native-reanimated
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-native-reanimated`
10
- **Platforms**: iOS, Android, Web, macOS, tvOS
11

12
## Core Imports
13

14
Default import (recommended):
15

16
```typescript
17
import Animated from "react-native-reanimated";
18
```
19

20
Named imports:
21

22
```typescript
23
import {
24
  useSharedValue,
25
  useAnimatedStyle,
26
  withTiming,
27
  withSpring,
28
  Easing
29
} from "react-native-reanimated";
30
```
31

32
CommonJS:
33

34
```javascript
35
const Animated = require("react-native-reanimated").default;
36
const { useSharedValue, useAnimatedStyle, withTiming } = require("react-native-reanimated");
37
```
38

39
## Basic Usage
40

41
```typescript
42
import React from "react";
43
import Animated, {
44
  useSharedValue,
45
  useAnimatedStyle,
46
  withTiming,
47
  withSpring,
48
} from "react-native-reanimated";
49
import { View, Button } from "react-native";
50

51
export default function BasicExample() {
52
  const scale = useSharedValue(1);
53
  const opacity = useSharedValue(1);
54

55
  const animatedStyle = useAnimatedStyle(() => ({
56
    transform: [{ scale: scale.value }],
57
    opacity: opacity.value,
58
  }));
59

60
  const handlePress = () => {
61
    scale.value = withSpring(scale.value === 1 ? 1.5 : 1);
62
    opacity.value = withTiming(opacity.value === 1 ? 0.5 : 1);
63
  };
64

65
  return (
66
    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
67
      <Animated.View
68
        style={[
69
          { width: 100, height: 100, backgroundColor: "blue" },
70
          animatedStyle,
71
        ]}
72
      />
73
      <Button title="Animate" onPress={handlePress} />
74
    </View>
75
  );
76
}
77
```
78

79
## Architecture
80

81
React Native Reanimated is built around several key components:
82

83
- **Shared Values**: Thread-safe values accessible from both JS and UI threads
84
- **Worklets**: JavaScript functions that can execute on the UI thread for optimal performance
85
- **Animation Functions**: Declarative animation utilities (`withTiming`, `withSpring`, etc.)
86
- **Animated Components**: High-performance versions of React Native components
87
- **Layout Animations**: Pre-built animations for component mounting, unmounting, and layout changes
88
- **Event Handlers**: Optimized handlers for gestures, scrolling, and other user interactions
89

90
## Capabilities
91

92
### Core Reactive System
93

94
Foundation for all Reanimated animations using shared values and reactive updates.
95

96
```typescript { .api }
97
function useSharedValue<T>(initialValue: T): SharedValue<T>;
98
function useAnimatedStyle<T>(
99
  updater: () => T,
100
  dependencies?: React.DependencyList
101
): AnimatedStyleHandle;
102
function useDerivedValue<T>(
103
  processor: () => T,
104
  dependencies?: React.DependencyList
105
): DerivedValue<T>;
106
```
107

108
[Core Reactive System](./core-reactive-system.md)
109

110
### Animation Functions
111

112
Declarative animation utilities for creating smooth, performant animations.
113

114
```typescript { .api }
115
function withTiming<T extends AnimatableValue>(
116
  toValue: T,
117
  config?: WithTimingConfig,
118
  callback?: AnimationCallback
119
): T;
120
function withSpring<T extends AnimatableValue>(
121
  toValue: T,
122
  config?: WithSpringConfig,
123
  callback?: AnimationCallback
124
): T;
125
function withDecay(
126
  config: WithDecayConfig,
127
  callback?: AnimationCallback
128
): number;
129
```
130

131
[Animation Functions](./animation-functions.md)
132

133
### Animated Components
134

135
High-performance animated versions of React Native components with optimized rendering.
136

137
```typescript { .api }
138
const Animated: {
139
  View: AnimatedComponent<typeof View>;
140
  Text: AnimatedComponent<typeof Text>;
141
  ScrollView: AnimatedComponent<typeof ScrollView>;
142
  Image: AnimatedComponent<typeof Image>;
143
  FlatList: AnimatedComponent<typeof FlatList>;
144
  createAnimatedComponent: <T>(component: T) => AnimatedComponent<T>;
145
};
146
```
147

148
[Animated Components](./animated-components.md)
149

150
### Layout Animations
151

152
Pre-built animations for component lifecycle events and layout changes.
153

154
```typescript { .api }
155
// Entry animations
156
const FadeIn: IEntryExitAnimationBuilder;
157
const SlideInLeft: IEntryExitAnimationBuilder;
158
const BounceIn: IEntryExitAnimationBuilder;
159

160
// Exit animations  
161
const FadeOut: IEntryExitAnimationBuilder;
162
const SlideOutRight: IEntryExitAnimationBuilder;
163
const BounceOut: IEntryExitAnimationBuilder;
164

165
// Layout transitions
166
const Layout: ILayoutAnimationBuilder;
167
const LinearTransition: ILayoutAnimationBuilder;
168
```
169

170
[Layout Animations](./layout-animations.md)
171

172
### Event Handling
173

174
Optimized handlers for user interactions, scrolling, and device events.
175

176
```typescript { .api }
177
function useAnimatedScrollHandler<T>(
178
  handler: ScrollHandler<T>
179
): ScrollHandlerProcessed<T>;
180
function useAnimatedReaction<T>(
181
  prepare: () => T,
182
  react: (prepared: T) => void,
183
  dependencies?: React.DependencyList
184
): void;
185
function useAnimatedKeyboard(): AnimatedKeyboardInfo;
186
```
187

188
[Event Handling](./event-handling.md)
189

190
### Interpolation and Easing
191

192
Mathematical functions for smooth value transitions and custom animation curves.
193

194
```typescript { .api }
195
function interpolate(
196
  value: number,
197
  inputRange: readonly number[],
198
  outputRange: readonly number[],
199
  extrapolate?: ExtrapolationType
200
): number;
201
function interpolateColor(
202
  value: number,
203
  inputRange: readonly number[],
204
  outputRange: readonly string[],
205
  colorSpace?: ColorSpace
206
): string;
207
```
208

209
[Interpolation and Easing](./interpolation-easing.md)
210

211
### Worklet Functions
212

213
Functions for executing code on the UI thread and managing worklet runtimes.
214

215
```typescript { .api }
216
function runOnUI<Args extends readonly unknown[], Return>(
217
  worklet: WorkletFunction<Args, Return>
218
): (...args: Args) => void;
219
function runOnJS<Args extends readonly unknown[], Return>(
220
  jsFunction: (...args: Args) => Return
221
): WorkletFunction<Args, void>;
222
```
223

224
[Worklet Functions](./worklet-functions.md)
225

226
### Platform Functions
227

228
Utilities for measuring components, scrolling, and native platform integration.
229

230
```typescript { .api }
231
function measure(ref: AnimatedRef<any>): MeasuredDimensions | null;
232
function scrollTo(
233
  ref: AnimatedRef<any>,
234
  x: number,
235
  y: number,
236
  animated: boolean
237
): void;
238
```
239

240
[Platform Functions](./platform-functions.md)
241

242
### CSS Integration
243

244
Web-compatible CSS animation and styling features that work across platforms.
245

246
```typescript { .api }
247
const css: {
248
  create: <T extends NamedStyles<T>>(styles: T) => T;
249
  keyframes: (keyframes: CSSAnimationKeyframes) => CSSKeyframesRule;
250
};
251
function cubicBezier(x1: number, y1: number, x2: number, y2: number): CubicBezierEasing;
252
function steps(stepsNumber: number, modifier?: StepsModifier): StepsEasing;
253
function linear(...points: ControlPoint[]): LinearEasing;
254
```
255

256
[CSS Integration](./css-integration.md)
257

258
### Screen Transitions
259

260
Gesture-driven screen navigation animations for React Native applications.
261

262
```typescript { .api }
263
function startScreenTransition(config: ScreenTransitionConfig): void;
264
function finishScreenTransition(config: ScreenTransitionConfig): void;
265
const ScreenTransition: {
266
  SwipeRight: AnimatedScreenTransition;
267
  SwipeLeft: AnimatedScreenTransition;
268
  SwipeDown: AnimatedScreenTransition;
269
  SwipeUp: AnimatedScreenTransition;
270
};
271
```
272

273
[Screen Transitions](./screen-transitions.md)
274

275
### Testing Utilities
276

277
Jest matchers and helper functions for testing animated components.
278

279
```typescript { .api }
280
function setUpTests(framerateConfig?: { fps?: number }): void;
281
function getAnimatedStyle(component: ReactTestInstance): DefaultStyle;
282
function advanceAnimationByTime(time?: number): void; // Deprecated
283
function advanceAnimationByFrame(count: number): void; // Deprecated  
284
function withReanimatedTimer(animationTest: () => void): void; // Deprecated
285
```
286

287
[Testing Utilities](./testing-utilities.md)
288

289
### Configuration and Utilities
290

291
Configuration functions, feature flags, and utility functions for customizing Reanimated.
292

293
```typescript { .api }
294
function addWhitelistedNativeProps(props: string[]): void;
295
function addWhitelistedUIProps(props: string[]): void;
296
function configureReanimatedLogger(config: LoggerConfig): void;
297
function getStaticFeatureFlag(flag: string): boolean | undefined;
298
function setDynamicFeatureFlag(flag: string, value: boolean): void;
299
function createAnimatedPropAdapter<T>(adapter: (props: T) => T): AnimatedPropAdapter<T>;
300
const reanimatedVersion: string;
301
```
302

303
[Configuration and Utilities](./configuration-utilities.md)
304

305
## Types
306

307
### Core Types
308

309
```typescript { .api }
310
interface SharedValue<T> {
311
  value: T;
312
  addListener: (listenerID: number, listener: (value: T) => void) => void;
313
  removeListener: (listenerID: number) => void;
314
  modify: (modifier: (value: T) => T) => void;
315
}
316

317
interface DerivedValue<T> {
318
  readonly value: T;
319
}
320

321
type AnimatableValue = number | string | number[];
322

323
interface AnimationCallback {
324
  (finished?: boolean, current?: AnimatableValue): void;
325
}
326

327
interface WithTimingConfig {
328
  duration?: number;
329
  easing?: EasingFunction;
330
  reduceMotion?: ReduceMotion;
331
}
332

333
interface WithSpringConfig {
334
  damping?: number;
335
  mass?: number;
336
  stiffness?: number;
337
  overshootClamping?: boolean;
338
  restDisplacementThreshold?: number;
339
  restSpeedThreshold?: number;
340
  velocity?: number | { x: number; y: number };
341
  reduceMotion?: ReduceMotion;
342
}
343

344
interface WithDecayConfig {
345
  deceleration?: number;
346
  velocity?: number;
347
  clamp?: readonly [number, number];
348
  velocityFactor?: number;
349
  rubberBandFactor?: number;
350
}
351
```
352

353
### Animation Types
354

355
```typescript { .api }
356
interface AnimationObject {
357
  __reanimatedWorkletInit?: boolean;
358
  __remoteFunction?: WorkletFunction;
359
  callback?: AnimationCallback;
360
  current?: AnimatableValue;
361
  finished?: boolean;
362
  strippedCurrent?: number;
363
  cancelled?: boolean;
364
  reduceMotion?: ReduceMotion;
365
}
366

367
enum ReduceMotion {
368
  System = "system",
369
  Always = "always",
370
  Never = "never"
371
}
372

373
enum Extrapolation {
374
  EXTEND = "extend",
375
  CLAMP = "clamp",
376
  IDENTITY = "identity"
377
}
378

379
type ExtrapolationType = Extrapolation;
380

381
enum ColorSpace {
382
  RGB = "rgb",
383
  HSV = "hsv"
384
}
385
```
386

387
### Component Types
388

389
```typescript { .api }
390
type AnimatedComponent<T> = T & {
391
  getAnimatedStyle?: () => any;
392
};
393

394
type AnimatedStyle<T = any> = {
395
  [K in keyof T]: T[K] | SharedValue<T[K]> | DerivedValue<T[K]>;
396
};
397

398
type AnimatedProps<T> = {
399
  [K in keyof T]: T[K] | SharedValue<T[K]> | DerivedValue<T[K]>;
400
};
401

402
interface AnimatedRef<T> {
403
  current: T | null;
404
  (component?: T | null): void;
405
}
406
```
407

408
### Layout Animation Types
409

410
```typescript { .api }
411
interface IEntryExitAnimationBuilder {
412
  duration(durationMs: number): IEntryExitAnimationBuilder;
413
  delay(delayMs: number): IEntryExitAnimationBuilder;
414
  springify(): IEntryExitAnimationBuilder;
415
  damping(dampingFactor: number): IEntryExitAnimationBuilder;
416
  mass(mass: number): IEntryExitAnimationBuilder;
417
  stiffness(stiffnessFactor: number): IEntryExitAnimationBuilder;
418
  overshootClamping(overshootClamping: number): IEntryExitAnimationBuilder;
419
  restDisplacementThreshold(restDisplacementThreshold: number): IEntryExitAnimationBuilder;
420
  restSpeedThreshold(restSpeedThreshold: number): IEntryExitAnimationBuilder;
421
  withCallback(callback: (finished: boolean) => void): IEntryExitAnimationBuilder;
422
  withInitialValues(values: StyleProps): IEntryExitAnimationBuilder;
423
  randomDelay(): IEntryExitAnimationBuilder;
424
  build(): LayoutAnimationFunction;
425
}
426

427
interface ILayoutAnimationBuilder {
428
  duration(durationMs: number): ILayoutAnimationBuilder;
429
  delay(delayMs: number): ILayoutAnimationBuilder;
430
  springify(): ILayoutAnimationBuilder;
431
  damping(dampingFactor: number): ILayoutAnimationBuilder;
432
  mass(mass: number): ILayoutAnimationBuilder;
433
  stiffness(stiffnessFactor: number): ILayoutAnimationBuilder;
434
  overshootClamping(overshootClamping: number): ILayoutAnimationBuilder;
435
  restDisplacementThreshold(restDisplacementThreshold: number): ILayoutAnimationBuilder;
436
  restSpeedThreshold(restSpeedThreshold: number): ILayoutAnimationBuilder;
437
  withCallback(callback: (finished: boolean) => void): ILayoutAnimationBuilder;
438
  randomDelay(): ILayoutAnimationBuilder;
439
  build(): LayoutAnimationFunction;
440
}
441
```