0
# Animated Components
1

2
High-performance animated versions of React Native components with optimized rendering that can efficiently handle animated properties and styles.
3

4
## Capabilities
5

6
### Built-in Animated Components
7

8
Pre-built animated versions of common React Native components.
9

10
```typescript { .api }
11
const Animated: {
12
  /** Animated version of React Native View */
13
  View: React.ComponentType<AnimatedProps<ViewProps>>;
14
  /** Animated version of React Native Text */
15
  Text: React.ComponentType<AnimatedProps<TextProps>>;
16
  /** Animated version of React Native ScrollView */
17
  ScrollView: React.ComponentType<AnimatedProps<ScrollViewProps>>;
18
  /** Animated version of React Native Image */
19
  Image: React.ComponentType<AnimatedProps<ImageProps>>;
20
  /** Animated version of React Native FlatList */
21
  FlatList: React.ComponentType<AnimatedProps<FlatListProps<any>>>;
22
};
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import React from "react";
29
import Animated, { 
30
  useSharedValue, 
31
  useAnimatedStyle, 
32
  withSpring 
33
} from "react-native-reanimated";
34
import { Button } from "react-native";
35

36
const MyComponent = () => {
37
  const opacity = useSharedValue(1);
38
  const scale = useSharedValue(1);
39
  const translateY = useSharedValue(0);
40

41
  const animatedStyle = useAnimatedStyle(() => ({
42
    opacity: opacity.value,
43
    transform: [
44
      { scale: scale.value },
45
      { translateY: translateY.value }
46
    ],
47
  }));
48

49
  const textStyle = useAnimatedStyle(() => ({
50
    color: opacity.value > 0.5 ? "black" : "gray",
51
    fontSize: 16 + scale.value * 4,
52
  }));
53

54
  const handlePress = () => {
55
    opacity.value = withSpring(opacity.value === 1 ? 0.3 : 1);
56
    scale.value = withSpring(scale.value === 1 ? 1.2 : 1);
57
    translateY.value = withSpring(translateY.value === 0 ? -20 : 0);
58
  };
59

60
  return (
61
    <>
62
      {/* Animated View */}
63
      <Animated.View
64
        style={[
65
          {
66
            width: 200,
67
            height: 100,
68
            backgroundColor: "lightblue",
69
            borderRadius: 10,
70
          },
71
          animatedStyle,
72
        ]}
73
      >
74
        {/* Animated Text inside */}
75
        <Animated.Text style={[{ textAlign: "center" }, textStyle]}>
76
          Animated Text
77
        </Animated.Text>
78
      </Animated.View>
79

80
      <Button title="Animate" onPress={handlePress} />
81
    </>
82
  );
83
};
84
```
85

86
### Animated ScrollView
87

88
Enhanced ScrollView with optimized scroll event handling and animated properties.
89

90
```typescript { .api }
91
interface AnimatedScrollViewProps extends ScrollViewProps {
92
  /** Animated scroll event handler */
93
  onScroll?: EventHandler<ScrollEvent>;
94
  /** Additional animated props */
95
  animatedProps?: AnimatedProps<ScrollViewProps>;
96
  /** Layout animation for scroll view */
97
  layout?: ILayoutAnimationBuilder;
98
}
99
```
100

101
**Usage Example:**
102

103
```typescript
104
import React from "react";
105
import Animated, { 
106
  useSharedValue, 
107
  useAnimatedScrollHandler,
108
  useAnimatedStyle,
109
  interpolate 
110
} from "react-native-reanimated";
111

112
const AnimatedScrollExample = () => {
113
  const scrollY = useSharedValue(0);
114
  const headerHeight = 100;
115

116
  const scrollHandler = useAnimatedScrollHandler({
117
    onScroll: (event) => {
118
      scrollY.value = event.contentOffset.y;
119
    },
120
  });
121

122
  const headerStyle = useAnimatedStyle(() => ({
123
    opacity: interpolate(scrollY.value, [0, headerHeight], [1, 0]),
124
    transform: [
125
      {
126
        translateY: interpolate(
127
          scrollY.value,
128
          [0, headerHeight],
129
          [0, -headerHeight / 2]
130
        ),
131
      },
132
    ],
133
  }));
134

135
  return (
136
    <>
137
      <Animated.View style={[{ height: headerHeight }, headerStyle]}>
138
        <Animated.Text>Parallax Header</Animated.Text>
139
      </Animated.View>
140
      
141
      <Animated.ScrollView
142
        onScroll={scrollHandler}
143
        scrollEventThrottle={16}
144
      >
145
        {/* Scroll content */}
146
        {Array.from({ length: 50 }).map((_, index) => (
147
          <Animated.View
148
            key={index}
149
            style={{
150
              height: 80,
151
              backgroundColor: index % 2 ? "lightgray" : "white",
152
              justifyContent: "center",
153
              alignItems: "center",
154
            }}
155
          >
156
            <Animated.Text>Item {index}</Animated.Text>
157
          </Animated.View>
158
        ))}
159
      </Animated.ScrollView>
160
    </>
161
  );
162
};
163
```
164

165
### Animated FlatList
166

167
High-performance animated list component with layout animations and optimized rendering.
168

169
```typescript { .api }
170
interface AnimatedFlatListProps<T> extends FlatListProps<T> {
171
  /** Layout animation for list items */
172
  itemLayoutAnimation?: IEntryExitAnimationBuilder;
173
  /** Animated scroll event handler */
174
  onScroll?: EventHandler<ScrollEvent>;
175
  /** Additional animated props */
176
  animatedProps?: AnimatedProps<FlatListProps<T>>;
177
}
178
```
179

180
**Usage Example:**
181

182
```typescript
183
import React, { useState } from "react";
184
import Animated, { 
185
  FadeInDown, 
186
  FadeOutUp,
187
  useAnimatedScrollHandler,
188
  useSharedValue 
189
} from "react-native-reanimated";
190
import { Button } from "react-native";
191

192
const AnimatedFlatListExample = () => {
193
  const [data, setData] = useState([1, 2, 3, 4, 5]);
194
  const scrollY = useSharedValue(0);
195

196
  const scrollHandler = useAnimatedScrollHandler({
197
    onScroll: (event) => {
198
      scrollY.value = event.contentOffset.y;
199
    },
200
  });
201

202
  const addItem = () => {
203
    setData(prev => [...prev, prev.length + 1]);
204
  };
205

206
  const removeItem = () => {
207
    setData(prev => prev.slice(0, -1));
208
  };
209

210
  const renderItem = ({ item, index }: { item: number; index: number }) => (
211
    <Animated.View
212
      entering={FadeInDown.delay(index * 100)}
213
      exiting={FadeOutUp}
214
      style={{
215
        height: 80,
216
        backgroundColor: "lightblue",
217
        marginVertical: 5,
218
        marginHorizontal: 10,
219
        borderRadius: 10,
220
        justifyContent: "center",
221
        alignItems: "center",
222
      }}
223
    >
224
      <Animated.Text>Item {item}</Animated.Text>
225
    </Animated.View>
226
  );
227

228
  return (
229
    <>
230
      <Button title="Add Item" onPress={addItem} />
231
      <Button title="Remove Item" onPress={removeItem} />
232
      
233
      <Animated.FlatList
234
        data={data}
235
        renderItem={renderItem}
236
        keyExtractor={(item) => item.toString()}
237
        onScroll={scrollHandler}
238
        scrollEventThrottle={16}
239
        showsVerticalScrollIndicator={false}
240
      />
241
    </>
242
  );
243
};
244
```
245

246
### Custom Animated Components
247

248
Create animated versions of any React Native component or custom component.
249

250
```typescript { .api }
251
/**
252
 * Creates an animated version of any component
253
 * @param component - React component to make animatable
254
 * @returns Animated version of the component
255
 */
256
function createAnimatedComponent<T extends React.ComponentType<any>>(
257
  component: T
258
): React.ComponentType<AnimatedProps<React.ComponentProps<T>>>;
259
```
260

261
**Usage Examples:**
262

263
```typescript
264
import React from "react";
265
import { TextInput, Switch } from "react-native";
266
import Animated, { 
267
  useSharedValue, 
268
  useAnimatedProps,
269
  useAnimatedStyle,
270
  withTiming 
271
} from "react-native-reanimated";
272

273
// Create animated versions of components
274
const AnimatedTextInput = Animated.createAnimatedComponent(TextInput);
275
const AnimatedSwitch = Animated.createAnimatedComponent(Switch);
276

277
const CustomAnimatedExample = () => {
278
  const inputOpacity = useSharedValue(1);
279
  const fontSize = useSharedValue(16);
280
  const switchValue = useSharedValue(false);
281

282
  // Animated props for TextInput
283
  const animatedTextInputProps = useAnimatedProps(() => ({
284
    placeholder: inputOpacity.value > 0.5 ? "Enter text..." : "Disabled",
285
    editable: inputOpacity.value > 0.5,
286
  }));
287

288
  // Animated style for TextInput
289
  const textInputStyle = useAnimatedStyle(() => ({
290
    opacity: inputOpacity.value,
291
    fontSize: fontSize.value,
292
    borderWidth: inputOpacity.value > 0.5 ? 2 : 1,
293
    borderColor: inputOpacity.value > 0.5 ? "blue" : "gray",
294
  }));
295

296
  // Animated props for Switch
297
  const animatedSwitchProps = useAnimatedProps(() => ({
298
    value: switchValue.value,
299
    trackColor: {
300
      false: "#767577",
301
      true: switchValue.value ? "#81b0ff" : "#767577",
302
    },
303
  }));
304

305
  const toggleInput = () => {
306
    inputOpacity.value = withTiming(inputOpacity.value === 1 ? 0.3 : 1);
307
    fontSize.value = withTiming(fontSize.value === 16 ? 20 : 16);
308
  };
309

310
  const toggleSwitch = () => {
311
    switchValue.value = withTiming(switchValue.value ? 0 : 1);
312
  };
313

314
  return (
315
    <Animated.View style={{ padding: 20 }}>
316
      {/* Animated TextInput */}
317
      <AnimatedTextInput
318
        style={[
319
          {
320
            height: 40,
321
            borderRadius: 5,
322
            paddingHorizontal: 10,
323
            marginBottom: 20,
324
          },
325
          textInputStyle,
326
        ]}
327
        animatedProps={animatedTextInputProps}
328
      />
329

330
      {/* Animated Switch */}
331
      <AnimatedSwitch
332
        animatedProps={animatedSwitchProps}
333
        onValueChange={toggleSwitch}
334
      />
335

336
      <Button title="Toggle Input" onPress={toggleInput} />
337
    </Animated.View>
338
  );
339
};
340
```
341

342
### Component Configuration
343

344
Utilities for configuring animated component behavior.
345

346
```typescript { .api }
347
/**
348
 * Add native props to the whitelist for animated components
349
 * @param props - Object mapping prop names to boolean values
350
 */
351
function addWhitelistedNativeProps(props: Record<string, boolean>): void;
352

353
/**
354
 * Add UI props to the whitelist for animated components  
355
 * @param props - Object mapping prop names to boolean values
356
 */
357
function addWhitelistedUIProps(props: Record<string, boolean>): void;
358
```
359

360
**Usage Example:**
361

362
```typescript
363
import { addWhitelistedNativeProps, addWhitelistedUIProps } from "react-native-reanimated";
364

365
// Allow custom native props to be animated
366
addWhitelistedNativeProps({
367
  customProp: true,
368
  specialAttribute: true,
369
});
370

371
// Allow custom UI props to be animated  
372
addWhitelistedUIProps({
373
  customStyleProp: true,
374
  animatedAttribute: true,
375
});
376
```
377

378
### Advanced Component Patterns
379

380
Complex usage patterns for animated components.
381

382
**Animated Component with Layout Animations:**
383

384
```typescript
385
import React, { useState } from "react";
386
import Animated, { 
387
  FadeIn, 
388
  FadeOut, 
389
  Layout,
390
  useAnimatedStyle,
391
  useSharedValue,
392
  withSpring 
393
} from "react-native-reanimated";
394

395
const AdvancedAnimatedExample = () => {
396
  const [items, setItems] = useState([1, 2, 3]);
397
  const containerScale = useSharedValue(1);
398

399
  const containerStyle = useAnimatedStyle(() => ({
400
    transform: [{ scale: containerScale.value }],
401
  }));
402

403
  const addItem = () => {
404
    setItems(prev => [...prev, prev.length + 1]);
405
    containerScale.value = withSpring(1.05, {}, () => {
406
      containerScale.value = withSpring(1);
407
    });
408
  };
409

410
  const removeItem = (id: number) => {
411
    setItems(prev => prev.filter(item => item !== id));
412
  };
413

414
  return (
415
    <Animated.View style={containerStyle}>
416
      {items.map((item) => (
417
        <Animated.View
418
          key={item}
419
          entering={FadeIn.springify()}
420
          exiting={FadeOut.duration(300)}
421
          layout={Layout.springify()}
422
          style={{
423
            height: 60,
424
            backgroundColor: "lightcoral",
425
            marginVertical: 5,
426
            borderRadius: 10,
427
            justifyContent: "center",
428
            alignItems: "center",
429
          }}
430
        >
431
          <Animated.Text>Item {item}</Animated.Text>
432
          <Button 
433
            title="Remove" 
434
            onPress={() => removeItem(item)} 
435
          />
436
        </Animated.View>
437
      ))}
438
      
439
      <Button title="Add Item" onPress={addItem} />
440
    </Animated.View>
441
  );
442
};
443
```
444

445
## Type Definitions
446

447
```typescript { .api }
448
type AnimatedProps<T> = {
449
  [K in keyof T]: T[K] | SharedValue<T[K]> | DerivedValue<T[K]>;
450
} & {
451
  animatedProps?: Partial<T>;
452
  layout?: ILayoutAnimationBuilder;
453
  entering?: IEntryExitAnimationBuilder;
454
  exiting?: IEntryExitAnimationBuilder;
455
};
456

457
type AnimatedComponent<T> = React.ComponentType<AnimatedProps<React.ComponentProps<T>>>;
458

459
interface ScrollEvent {
460
  contentOffset: {
461
    x: number;
462
    y: number;
463
  };
464
  contentSize: {
465
    height: number;
466
    width: number;
467
  };
468
  layoutMeasurement: {
469
    height: number;
470
    width: number;
471
  };
472
}
473

474
interface FlatListPropsWithLayout<T> extends FlatListProps<T> {
475
  itemLayoutAnimation?: IEntryExitAnimationBuilder;
476
}
477
```