0
# Custom Animations
1

2
Create custom keyframe-based animations with full control over timing, styling, and easing. Define animations using either simple from/to syntax or detailed keyframe sequences.
3

4
## Capabilities
5

6
### Create Animation
7

8
Transform animation definition objects into compiled animations ready for use with animatable components.
9

10
```javascript { .api }
11
/**
12
 * Creates a compiled animation from a definition object
13
 * @param definition - Animation definition with keyframes and optional properties
14
 * @returns Compiled animation object with interpolation ranges
15
 */
16
function createAnimation(definition: CustomAnimation): object;
17

18
interface CustomAnimation {
19
  /** Starting styles (equivalent to keyframe 0) */
20
  from?: StyleObject;
21
  /** Ending styles (equivalent to keyframe 1) */
22
  to?: StyleObject;
23
  /** Static styles applied throughout animation (for perspective, zIndex, etc.) */
24
  style?: StyleObject;
25
  /** Default easing function for the animation */
26
  easing?: Easing;
27
  /** Keyframes defined by progress (0-1) with style objects */
28
  [progress: number]: StyleObject;
29
}
30

31
type StyleObject = {
32
  [key: string]: any;
33
};
34
```
35

36
**Basic Usage Examples:**
37

38
```javascript
39
import * as Animatable from 'react-native-animatable';
40

41
// Simple fade animation
42
const fadeIn = {
43
  from: {
44
    opacity: 0,
45
  },
46
  to: {
47
    opacity: 1,
48
  },
49
};
50

51
// Use directly as animation prop
52
<Animatable.Text animation={fadeIn}>
53
  Fade me in
54
</Animatable.Text>
55

56
// Complex multi-keyframe animation
57
const zoomOut = {
58
  0: {
59
    opacity: 1,
60
    scale: 1,
61
  },
62
  0.5: {
63
    opacity: 1,
64
    scale: 0.3,
65
  },
66
  1: {
67
    opacity: 0,
68
    scale: 0,
69
  },
70
};
71

72
<Animatable.Text animation={zoomOut}>
73
  Zoom me out
74
</Animatable.Text>
75
```
76

77
### Simple From/To Animations
78

79
Create straightforward animations using from and to states.
80

81
**Usage Examples:**
82

83
```javascript
84
// Color transition
85
const colorChange = {
86
  from: {
87
    backgroundColor: 'red',
88
  },
89
  to: {
90
    backgroundColor: 'blue',
91
  },
92
};
93

94
// Scale animation
95
const scaleUp = {
96
  from: {
97
    scale: 0.5,
98
  },
99
  to: {
100
    scale: 1.2,
101
  },
102
};
103

104
// Rotation animation
105
const spin = {
106
  from: {
107
    rotate: '0deg',
108
  },
109
  to: {
110
    rotate: '360deg',
111
  },
112
};
113

114
// Combined transforms
115
const slideAndFade = {
116
  from: {
117
    opacity: 0,
118
    translateX: -100,
119
  },
120
  to: {
121
    opacity: 1,
122
    translateX: 0,
123
  },
124
};
125

126
// Usage
127
<Animatable.View animation={slideAndFade} duration={800}>
128
  <Text>I slide in and fade!</Text>
129
</Animatable.View>
130
```
131

132
### Multi-Keyframe Animations
133

134
Create complex animations with multiple keyframes for precise control over animation progression.
135

136
**Usage Examples:**
137

138
```javascript
139
// Bounce effect with multiple keyframes
140
const customBounce = {
141
  0: {
142
    translateY: 0,
143
    scale: 1,
144
  },
145
  0.3: {
146
    translateY: -50,
147
    scale: 1.1,
148
  },
149
  0.6: {
150
    translateY: 0,
151
    scale: 0.9,
152
  },
153
  0.8: {
154
    translateY: -20,
155
    scale: 1.05,
156
  },
157
  1: {
158
    translateY: 0,
159
    scale: 1,
160
  },
161
};
162

163
// Complex wave animation
164
const wave = {
165
  0: {
166
    rotateZ: '0deg',
167
    scale: 1,
168
  },
169
  0.25: {
170
    rotateZ: '15deg',
171
    scale: 1.1,
172
  },
173
  0.5: {
174
    rotateZ: '0deg',
175
    scale: 1,
176
  },
177
  0.75: {
178
    rotateZ: '-15deg',
179
    scale: 0.9,
180
  },
181
  1: {
182
    rotateZ: '0deg',
183
    scale: 1,
184
  },
185
};
186

187
// Morphing animation
188
const morph = {
189
  0: {
190
    borderRadius: 0,
191
    backgroundColor: 'red',
192
    scale: 1,
193
  },
194
  0.33: {
195
    borderRadius: 25,
196
    backgroundColor: 'orange',
197
    scale: 1.2,
198
  },
199
  0.66: {
200
    borderRadius: 50,
201
    backgroundColor: 'yellow',
202
    scale: 0.8,
203
  },
204
  1: {
205
    borderRadius: 100,
206
    backgroundColor: 'green',
207
    scale: 1,
208
  },
209
};
210
```
211

212
### Animations with Static Styles
213

214
Define static styles that persist throughout the animation, useful for 3D transforms and layering.
215

216
**Usage Examples:**
217

218
```javascript
219
// 3D flip with perspective
220
const flip3D = {
221
  style: {
222
    backfaceVisibility: 'hidden',
223
    perspective: 1000,
224
  },
225
  from: {
226
    rotateY: '0deg',
227
  },
228
  to: {
229
    rotateY: '180deg',
230
  },
231
};
232

233
// Layered animation with z-index
234
const popUp = {
235
  style: {
236
    zIndex: 999,
237
    elevation: 10,
238
  },
239
  from: {
240
    scale: 0,
241
    opacity: 0,
242
  },
243
  to: {
244
    scale: 1,
245
    opacity: 1,
246
  },
247
};
248

249
// Card flip animation
250
const cardFlip = {
251
  style: {
252
    backfaceVisibility: 'hidden',
253
    perspective: 1000,
254
  },
255
  0: {
256
    rotateY: '0deg',
257
  },
258
  0.5: {
259
    rotateY: '90deg',
260
  },
261
  1: {
262
    rotateY: '180deg',
263
  },
264
};
265
```
266

267
### Animations with Custom Easing
268

269
Define default easing functions for smoother animation curves.
270

271
**Usage Examples:**
272

273
```javascript
274
// Smooth elastic animation
275
const elasticScale = {
276
  easing: 'ease-out-back',
277
  from: {
278
    scale: 0,
279
  },
280
  to: {
281
    scale: 1,
282
  },
283
};
284

285
// Quick bounce with custom timing
286
const quickBounce = {
287
  easing: 'ease-in-out-cubic',
288
  0: {
289
    translateY: 0,
290
  },
291
  0.4: {
292
    translateY: -30,
293
  },
294
  0.6: {
295
    translateY: -30,
296
  },
297
  1: {
298
    translateY: 0,
299
  },
300
};
301

302
// Slow fade with sine easing
303
const slowFade = {
304
  easing: 'ease-in-out-sine',
305
  from: {
306
    opacity: 1,
307
  },
308
  to: {
309
    opacity: 0,
310
  },
311
};
312
```
313

314
## Animation Compilation
315

316
The `createAnimation` function processes definitions and creates optimized interpolation objects:
317

318
```javascript
319
// Input definition
320
const definition = {
321
  from: { opacity: 0, scale: 0.5 },
322
  to: { opacity: 1, scale: 1 },
323
};
324

325
// Compiled output (simplified)
326
const compiled = {
327
  opacity: {
328
    inputRange: [0, 1],
329
    outputRange: [0, 1],
330
  },
331
  scale: {
332
    inputRange: [0, 1],
333
    outputRange: [0.5, 1],
334
  },
335
};
336
```
337

338
## Advanced Custom Animations
339

340
### Staggered Element Animation
341

342
```javascript
343
// Create staggered entrance animation
344
const staggeredFadeIn = (delay = 0) => ({
345
  from: {
346
    opacity: 0,
347
    translateY: 20,
348
  },
349
  to: {
350
    opacity: 1,
351
    translateY: 0,
352
  },
353
});
354

355
// Usage with delays
356
{items.map((item, index) => (
357
  <Animatable.View
358
    key={item.id}
359
    animation={staggeredFadeIn()}
360
    delay={index * 100}
361
    duration={500}
362
  >
363
    <Text>{item.text}</Text>
364
  </Animatable.View>
365
))}
366
```
367

368
### Loading Animation
369

370
```javascript
371
// Pulsing loader
372
const pulse = {
373
  0: {
374
    scale: 1,
375
    opacity: 1,
376
  },
377
  0.5: {
378
    scale: 1.2,
379
    opacity: 0.7,
380
  },
381
  1: {
382
    scale: 1,
383
    opacity: 1,
384
  },
385
};
386

387
<Animatable.View 
388
  animation={pulse} 
389
  iterationCount="infinite" 
390
  duration={1000}
391
>
392
  <LoadingSpinner />
393
</Animatable.View>
394
```
395

396
### Success Animation
397

398
```javascript
399
// Checkmark success animation
400
const successCheck = {
401
  style: {
402
    overflow: 'hidden',
403
  },
404
  0: {
405
    scale: 0,
406
    rotate: '-45deg',
407
  },
408
  0.6: {
409
    scale: 1.1,
410
    rotate: '0deg',
411
  },
412
  1: {
413
    scale: 1,
414
    rotate: '0deg',
415
  },
416
};
417

418
<Animatable.View animation={successCheck} duration={600}>
419
  <Icon name="check" size={50} color="green" />
420
</Animatable.View>
421
```
422

423
## Color Animations
424

425
```javascript
426
// Note: Use rgba() syntax for color animations
427
const colorPulse = {
428
  0: {
429
    backgroundColor: 'rgba(255, 0, 0, 1)',
430
  },
431
  0.5: {
432
    backgroundColor: 'rgba(255, 0, 0, 0.5)',
433
  },
434
  1: {
435
    backgroundColor: 'rgba(255, 0, 0, 1)',
436
  },
437
};
438

439
const gradientShift = {
440
  from: {
441
    backgroundColor: 'rgba(100, 150, 200, 1)',
442
  },
443
  to: {
444
    backgroundColor: 'rgba(200, 100, 150, 1)',
445
  },
446
};
447
```