0
# Core Reactive System
1

2
The reactive system is the foundation of React Native Reanimated, providing thread-safe values and reactive updates that enable high-performance animations running on the UI thread.
3

4
## Capabilities
5

6
### Shared Values
7

8
Creates values that can be safely accessed and modified from both JavaScript and UI threads.
9

10
```typescript { .api }
11
/**
12
 * Creates a shared value that can be accessed from both JS and UI threads
13
 * @param initialValue - The initial value
14
 * @returns SharedValue instance with .value property
15
 */
16
function useSharedValue<T>(initialValue: T): SharedValue<T>;
17

18
interface SharedValue<T> {
19
  /** Current value - can be read and written from both threads */
20
  value: T;
21
  /** Get the current value (alternative to .value property) */
22
  get(): T;
23
  /** Set the value with optional updater function */
24
  set(value: T | ((value: T) => T)): void;
25
  /** Add a listener that triggers when value changes */
26
  addListener: (listenerID: number, listener: (value: T) => void) => void;
27
  /** Remove a value change listener */
28
  removeListener: (listenerID: number) => void;
29
  /** Modify value using a transform function */
30
  modify: (modifier?: (value: T) => T, forceUpdate?: boolean) => void;
31
}
32
```
33

34
**Usage Examples:**
35

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

39
// Basic shared values
40
const opacity = useSharedValue(1);
41
const scale = useSharedValue(1);
42
const position = useSharedValue({ x: 0, y: 0 });
43

44
// Reading and writing values
45
opacity.value = 0.5;
46
position.value = { x: 100, y: 200 };
47

48
// Using in animations
49
const handlePress = () => {
50
  opacity.value = withTiming(opacity.value === 1 ? 0 : 1);
51
};
52
```
53

54
### Animated Styles
55

56
Creates reactive style objects that automatically update when shared values change.
57

58
```typescript { .api }
59
/**
60
 * Creates an animated style object that updates when dependencies change
61
 * @param updater - Function returning style object using shared values
62
 * @param dependencies - Optional dependency array for optimization
63
 * @returns Animated style handle for use in component style prop
64
 */
65
function useAnimatedStyle<T>(
66
  updater: () => T,
67
  dependencies?: React.DependencyList
68
): AnimatedStyleHandle;
69

70
type AnimatedStyleHandle = object;
71
```
72

73
**Usage Examples:**
74

75
```typescript
76
import { useAnimatedStyle, useSharedValue, withSpring } from "react-native-reanimated";
77

78
const MyComponent = () => {
79
  const scale = useSharedValue(1);
80
  const rotation = useSharedValue(0);
81

82
  // Basic animated style
83
  const animatedStyle = useAnimatedStyle(() => ({
84
    transform: [
85
      { scale: scale.value },
86
      { rotate: `${rotation.value}deg` }
87
    ],
88
  }));
89

90
  // Style with conditional logic
91
  const conditionalStyle = useAnimatedStyle(() => ({
92
    backgroundColor: scale.value > 1.2 ? "red" : "blue",
93
    borderRadius: scale.value * 10,
94
  }));
95

96
  // Using dependency array for optimization
97
  const optimizedStyle = useAnimatedStyle(() => ({
98
    opacity: scale.value > 1 ? 1 : 0.5,
99
  }), []);
100

101
  return (
102
    <Animated.View style={[baseStyle, animatedStyle]} />
103
  );
104
};
105
```
106

107
### Derived Values
108

109
Creates read-only values computed from other shared values, with automatic updates.
110

111
```typescript { .api }
112
/**
113
 * Creates a derived value that automatically updates when dependencies change
114
 * @param processor - Function computing the derived value
115
 * @param dependencies - Optional dependency array for optimization
116
 * @returns Read-only derived value
117
 */
118
function useDerivedValue<T>(
119
  processor: () => T,
120
  dependencies?: React.DependencyList
121
): DerivedValue<T>;
122

123
interface DerivedValue<T> {
124
  /** Read-only computed value */
125
  readonly value: T;
126
}
127
```
128

129
**Usage Examples:**
130

131
```typescript
132
import { useDerivedValue, useSharedValue, interpolate } from "react-native-reanimated";
133

134
const MyComponent = () => {
135
  const scrollY = useSharedValue(0);
136
  const scale = useSharedValue(1);
137

138
  // Simple derived value
139
  const isScrolledDown = useDerivedValue(() => scrollY.value > 100);
140

141
  // Complex computation
142
  const headerOpacity = useDerivedValue(() => {
143
    return interpolate(
144
      scrollY.value,
145
      [0, 100, 200],
146
      [1, 0.5, 0],
147
      Extrapolation.CLAMP
148
    );
149
  });
150

151
  // Combining multiple shared values
152
  const combinedTransform = useDerivedValue(() => ({
153
    scale: scale.value,
154
    translateY: scrollY.value * -0.5,
155
  }));
156

157
  const animatedStyle = useAnimatedStyle(() => ({
158
    opacity: headerOpacity.value,
159
    transform: [
160
      { scale: combinedTransform.value.scale },
161
      { translateY: combinedTransform.value.translateY }
162
    ],
163
  }));
164

165
  return <Animated.View style={animatedStyle} />;
166
};
167
```
168

169
### Animated Props
170

171
Creates reactive props for components beyond styling.
172

173
```typescript { .api }
174
/**
175
 * Creates animated props that update when shared values change
176
 * @param updater - Function returning props object using shared values
177
 * @param dependencies - Optional dependency array for optimization
178
 * @returns Animated props object for component props
179
 */
180
function useAnimatedProps<T>(
181
  updater: () => Partial<T>,
182
  dependencies?: React.DependencyList
183
): AnimatedProps<T>;
184

185
type AnimatedProps<T> = {
186
  [K in keyof T]: T[K] | SharedValue<T[K]> | DerivedValue<T[K]>;
187
};
188
```
189

190
**Usage Examples:**
191

192
```typescript
193
import { useAnimatedProps, useSharedValue } from "react-native-reanimated";
194
import { TextInput } from "react-native";
195

196
const AnimatedTextInput = Animated.createAnimatedComponent(TextInput);
197

198
const MyComponent = () => {
199
  const inputOpacity = useSharedValue(1);
200
  const fontSize = useSharedValue(16);
201

202
  // Animated props for TextInput
203
  const animatedProps = useAnimatedProps(() => ({
204
    placeholder: inputOpacity.value > 0.5 ? "Enter text" : "Disabled",
205
    editable: inputOpacity.value > 0.5,
206
  }));
207

208
  // Animated style combined with props
209
  const animatedStyle = useAnimatedStyle(() => ({
210
    opacity: inputOpacity.value,
211
    fontSize: fontSize.value,
212
  }));
213

214
  return (
215
    <AnimatedTextInput
216
      style={animatedStyle}
217
      animatedProps={animatedProps}
218
    />
219
  );
220
};
221
```
222

223
### Core Utilities
224

225
Essential functions for working with shared values and creating reactive updates.
226

227
```typescript { .api }
228
/**
229
 * Creates a mutable shared value (alternative to useSharedValue for non-hook contexts)
230
 * @param initialValue - The initial value
231
 * @returns SharedValue instance
232
 */
233
function makeMutable<T>(initialValue: T): SharedValue<T>;
234

235
/**
236
 * Checks if a value is a SharedValue instance
237
 * @param value - Value to check
238
 * @returns True if value is a SharedValue
239
 */
240
function isSharedValue(value: any): value is SharedValue<any>;
241

242
/**
243
 * Checks if Reanimated is properly configured
244
 * @returns True if Reanimated is configured correctly
245
 */
246
function isConfigured(): boolean;
247

248
/**
249
 * Checks if running Reanimated version 3
250
 * @returns True if using Reanimated 3+
251
 */
252
function isReanimated3(): boolean;
253
```
254

255
**Usage Examples:**
256

257
```typescript
258
import { makeMutable, isSharedValue } from "react-native-reanimated";
259

260
// Creating shared values outside components
261
const globalCounter = makeMutable(0);
262

263
// Type guards
264
const handleValue = (value: unknown) => {
265
  if (isSharedValue(value)) {
266
    console.log("Current value:", value.value);
267
    value.value = value.value + 1;
268
  }
269
};
270

271
// Configuration checks
272
if (isConfigured()) {
273
  console.log("Reanimated is ready to use");
274
}
275
```
276

277
### Value Reactions
278

279
React to changes in shared values with custom side effects.
280

281
```typescript { .api }
282
/**
283
 * React to changes in shared values with custom side effects
284
 * @param prepare - Function to prepare values (runs on UI thread)
285
 * @param react - Function to handle changes (runs on JS thread)
286
 * @param dependencies - Optional dependency array
287
 */
288
function useAnimatedReaction<T>(
289
  prepare: () => T,
290
  react: (prepared: T, previous: T | null) => void,
291
  dependencies?: React.DependencyList
292
): void;
293
```
294

295
**Usage Example:**
296

297
```typescript
298
import { useAnimatedReaction, useSharedValue, runOnJS } from "react-native-reanimated";
299

300
const MyComponent = () => {
301
  const scrollY = useSharedValue(0);
302
  
303
  // React to scroll changes
304
  useAnimatedReaction(
305
    () => scrollY.value > 100,
306
    (isScrolledDown, wasScrolledDown) => {
307
      if (isScrolledDown !== wasScrolledDown) {
308
        runOnJS(handleScrollThreshold)(isScrolledDown);
309
      }
310
    }
311
  );
312

313
  const handleScrollThreshold = (isScrolledDown: boolean) => {
314
    console.log("Scroll threshold crossed:", isScrolledDown);
315
  };
316

317
  return <ScrollView onScroll={scrollHandler} />;
318
};
319
```
320

321
## Type Definitions
322

323
```typescript { .api }
324
type AnimatableValue = number | string | number[];
325

326
interface AnimatedStyleHandle {
327
  [key: string]: any;
328
}
329

330
type StyleProps = {
331
  [key: string]: AnimatableValue | StyleProps;
332
};
333

334
interface MeasuredDimensions {
335
  x: number;
336
  y: number;
337
  width: number;
338
  height: number;
339
  pageX: number;
340
  pageY: number;
341
}
342
```