0
# Declarative Animation
1

2
Props-based animation control with extensive configuration options for timing, easing, and behavior. Configure animations through component props for simple, declarative animation management.
3

4
## Capabilities
5

6
### Animation Prop
7

8
Specify animations using the animation prop with built-in names, custom definitions, or registered animations.
9

10
```javascript { .api }
11
interface AnimationProp {
12
  /** Built-in animation name, custom animation object, or registered animation name */
13
  animation?: Animation | string | CustomAnimation;
14
}
15

16
type Animation = 'bounce' | 'flash' | 'jello' | /* ... all built-in animations */;
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
// Built-in animation by name
23
<Animatable.Text animation="bounceIn">
24
  Built-in animation
25
</Animatable.Text>
26

27
// Custom animation object
28
<Animatable.View animation={{
29
  from: { opacity: 0, scale: 0 },
30
  to: { opacity: 1, scale: 1 }
31
}}>
32
  Custom animation
33
</Animatable.View>
34

35
// Registered animation by name
36
<Animatable.View animation="myCustomAnimation">
37
  Registered animation
38
</Animatable.View>
39
```
40

41
### Timing Configuration
42

43
Control animation timing with duration, delay, and iteration properties.
44

45
```javascript { .api }
46
interface TimingProps {
47
  /** Animation duration in milliseconds (default: 1000) */
48
  duration?: number;
49
  /** Delay before animation starts in milliseconds (default: 0) */
50
  delay?: number;
51
  /** Number of times to repeat animation or 'infinite' (default: 1) */
52
  iterationCount?: number | 'infinite';
53
  /** Delay between animation iterations in milliseconds (default: 0) */
54
  iterationDelay?: number;
55
}
56
```
57

58
**Usage Examples:**
59

60
```javascript
61
// Long duration with delay
62
<Animatable.Text 
63
  animation="fadeIn" 
64
  duration={2000} 
65
  delay={500}
66
>
67
  Slow fade with delay
68
</Animatable.Text>
69

70
// Infinite looping animation
71
<Animatable.View 
72
  animation="pulse" 
73
  iterationCount="infinite"
74
  duration={800}
75
>
76
  ❤️ Infinite pulse
77
</Animatable.View>
78

79
// Multiple iterations with delays
80
<Animatable.View 
81
  animation="bounce" 
82
  iterationCount={3}
83
  iterationDelay={1000}
84
  duration={600}
85
>
86
  Bounce 3 times with pauses
87
</Animatable.View>
88
```
89

90
### Direction Control
91

92
Control animation playback direction for more complex animation patterns.
93

94
```javascript { .api }
95
interface DirectionProps {
96
  /** Animation playback direction (default: 'normal') */
97
  direction?: 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
98
}
99
```
100

101
**Usage Examples:**
102

103
```javascript
104
// Reverse animation
105
<Animatable.View 
106
  animation="slideInLeft" 
107
  direction="reverse"
108
>
109
  Slides out to the left
110
</Animatable.View>
111

112
// Alternating direction for smooth loops
113
<Animatable.View 
114
  animation="slideInDown" 
115
  iterationCount="infinite"
116
  direction="alternate"
117
  duration={1000}
118
>
119
  Up and down motion
120
</Animatable.View>
121

122
// Alternate reverse starts backwards
123
<Animatable.View 
124
  animation="bounce" 
125
  iterationCount={4}
126
  direction="alternate-reverse"
127
>
128
  Bounce pattern starting reversed
129
</Animatable.View>
130
```
131

132
### Easing Functions
133

134
Specify easing functions for smooth animation curves.
135

136
```javascript { .api }
137
interface EasingProps {
138
  /** Easing function name or custom function (default: 'ease') */
139
  easing?: Easing;
140
}
141

142
type Easing = 
143
  | 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out'
144
  | 'ease-in-cubic' | 'ease-out-cubic' | 'ease-in-out-cubic'
145
  | 'ease-in-circ' | 'ease-out-circ' | 'ease-in-out-circ'
146
  | 'ease-in-expo' | 'ease-out-expo' | 'ease-in-out-expo'
147
  | 'ease-in-quad' | 'ease-out-quad' | 'ease-in-out-quad'
148
  | 'ease-in-quart' | 'ease-out-quart' | 'ease-in-out-quart'
149
  | 'ease-in-quint' | 'ease-out-quint' | 'ease-in-out-quint'
150
  | 'ease-in-sine' | 'ease-out-sine' | 'ease-in-out-sine'
151
  | 'ease-in-back' | 'ease-out-back' | 'ease-in-out-back'
152
  | ((t: number) => number);
153
```
154

155
**Usage Examples:**
156

157
```javascript
158
// Smooth ease-out for natural motion
159
<Animatable.View 
160
  animation="slideInUp" 
161
  easing="ease-out"
162
  duration={600}
163
>
164
  Natural slide motion
165
</Animatable.View>
166

167
// Elastic back easing for playful effect
168
<Animatable.View 
169
  animation="zoomIn" 
170
  easing="ease-out-back"
171
  duration={800}
172
>
173
  Elastic zoom effect
174
</Animatable.View>
175

176
// Linear for consistent motion
177
<Animatable.View 
178
  animation="rotate" 
179
  easing="linear"
180
  iterationCount="infinite"
181
  duration={2000}
182
>
183
  Constant rotation speed
184
</Animatable.View>
185

186
// Custom easing function
187
<Animatable.View 
188
  animation="fadeIn"
189
  easing={(t) => t * t * (3 - 2 * t)} // Smoothstep
190
  duration={1000}
191
>
192
  Custom smoothstep easing
193
</Animatable.View>
194
```
195

196
### Transition Animations
197

198
Animate style property changes automatically when props change.
199

200
```javascript { .api }
201
interface TransitionProps {
202
  /** Style property names to animate on change */
203
  transition?: string | string[];
204
}
205
```
206

207
**Usage Examples:**
208

209
```javascript
210
// Single property transition
211
<Animatable.View 
212
  transition="backgroundColor"
213
  style={{ backgroundColor: this.state.bgColor }}
214
  duration={300}
215
>
216
  Background color animates on change
217
</Animatable.View>
218

219
// Multiple property transitions
220
<Animatable.View 
221
  transition={['opacity', 'scale']}
222
  style={{ 
223
    opacity: this.state.visible ? 1 : 0,
224
    transform: [{ scale: this.state.scale }]
225
  }}
226
  duration={400}
227
  easing="ease-out"
228
>
229
  Opacity and scale animate together
230
</Animatable.View>
231

232
// Font size transition
233
<TouchableOpacity onPress={() => this.setState({
234
  fontSize: (this.state.fontSize || 10) + 5 
235
})}>
236
  <Animatable.Text 
237
    transition="fontSize" 
238
    style={{ fontSize: this.state.fontSize || 10 }}
239
  >
240
    Size me up, Scotty
241
  </Animatable.Text>
242
</TouchableOpacity>
243
```
244

245
### Performance Options
246

247
Control animation performance and interaction behavior.
248

249
```javascript { .api }
250
interface PerformanceProps {
251
  /** Use native animation driver for better performance (default: false) */
252
  useNativeDriver?: boolean;
253
  /** Create interaction handle on InteractionManager */
254
  isInteraction?: boolean;
255
}
256
```
257

258
**Usage Examples:**
259

260
```javascript
261
// Native driver for transform animations
262
<Animatable.View 
263
  animation="slideInLeft"
264
  useNativeDriver={true}
265
  duration={300}
266
>
267
  Hardware-accelerated animation
268
</Animatable.View>
269

270
// Interaction handle for important animations
271
<Animatable.View 
272
  animation="fadeIn"
273
  isInteraction={true}
274
  duration={1000}
275
>
276
  Blocks interactions until complete
277
</Animatable.View>
278

279
// Note: Native driver limitations
280
<Animatable.View 
281
  animation={{
282
    from: { opacity: 0, translateX: -100 }, // ✅ Works with native driver
283
    to: { opacity: 1, translateX: 0 }
284
  }}
285
  useNativeDriver={true}
286
/>
287

288
<Animatable.View 
289
  animation={{
290
    from: { backgroundColor: 'red' }, // ❌ Doesn't work with native driver
291
    to: { backgroundColor: 'blue' }
292
  }}
293
  useNativeDriver={false} // Must use JS driver for colors
294
/>
295
```
296

297
### Event Callbacks
298

299
Respond to animation lifecycle events with callback functions.
300

301
```javascript { .api }
302
interface CallbackProps {
303
  /** Called when animation begins */
304
  onAnimationBegin?: () => void;
305
  /** Called when animation ends with completion state */
306
  onAnimationEnd?: (endState: { finished: boolean }) => void;
307
  /** Called when transition begins for a specific property */
308
  onTransitionBegin?: (property: string) => void;
309
  /** Called when transition ends for a specific property */
310
  onTransitionEnd?: (property: string) => void;
311
}
312
```
313

314
**Usage Examples:**
315

316
```javascript
317
class AnimatedComponent extends Component {
318
  state = { animating: false };
319
  
320
  handleAnimationBegin = () => {
321
    console.log('Animation started!');
322
    this.setState({ animating: true });
323
  };
324
  
325
  handleAnimationEnd = (endState) => {
326
    console.log('Animation finished:', endState.finished);
327
    this.setState({ animating: false });
328
    
329
    if (endState.finished) {
330
      // Animation completed successfully
331
      this.showNextAnimation();
332
    } else {
333
      // Animation was cancelled
334
      this.resetToInitialState();
335
    }
336
  };
337
  
338
  handleTransitionBegin = (property) => {
339
    console.log(`Transition started for: ${property}`);
340
  };
341
  
342
  handleTransitionEnd = (property) => {
343
    console.log(`Transition ended for: ${property}`);
344
  };
345
  
346
  render() {
347
    return (
348
      <Animatable.View
349
        animation="bounceIn"
350
        duration={1000}
351
        onAnimationBegin={this.handleAnimationBegin}
352
        onAnimationEnd={this.handleAnimationEnd}
353
        transition={['opacity', 'scale']}
354
        onTransitionBegin={this.handleTransitionBegin}
355
        onTransitionEnd={this.handleTransitionEnd}
356
        style={{ 
357
          opacity: this.state.visible ? 1 : 0.5,
358
          transform: [{ scale: this.state.scale || 1 }]
359
        }}
360
      >
361
        <Text>Animated content</Text>
362
      </Animatable.View>
363
    );
364
  }
365
}
366
```
367

368
## Complete Props Interface
369

370
```javascript { .api }
371
interface AnimatableProps {
372
  animation?: Animation | string | CustomAnimation;
373
  duration?: number;
374
  delay?: number;
375
  direction?: 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
376
  easing?: Easing;
377
  iterationCount?: number | 'infinite';
378
  iterationDelay?: number;
379
  transition?: string | string[];
380
  useNativeDriver?: boolean;
381
  isInteraction?: boolean;
382
  onAnimationBegin?: () => void;
383
  onAnimationEnd?: (endState: { finished: boolean }) => void;
384
  onTransitionBegin?: (property: string) => void;
385
  onTransitionEnd?: (property: string) => void;
386
}
387
```
388

389
## Advanced Declarative Patterns
390

391
### Conditional Animations
392

393
```javascript
394
// Animation based on state
395
<Animatable.View 
396
  animation={this.state.isVisible ? "fadeIn" : "fadeOut"}
397
  duration={300}
398
>
399
  <Text>Conditional animation</Text>
400
</Animatable.View>
401

402
// Different animations for different states
403
<Animatable.View 
404
  animation={
405
    this.state.loading ? "pulse" : 
406
    this.state.error ? "shake" : 
407
    this.state.success ? "bounce" : null
408
  }
409
  iterationCount={this.state.loading ? "infinite" : 1}
410
>
411
  <StatusContent />
412
</Animatable.View>
413
```
414

415
### Responsive Animation Duration
416

417
```javascript
418
// Duration based on screen size or user preferences
419
<Animatable.View 
420
  animation="slideInRight"
421
  duration={this.props.reducedMotion ? 100 : 600}
422
  easing={this.props.reducedMotion ? "linear" : "ease-out"}
423
>
424
  <Content />
425
</Animatable.View>
426
```
427

428
### Chained Animations with Delays
429

430
```javascript
431
// Sequential animations with delays
432
<View>
433
  <Animatable.Text animation="fadeInUp" delay={0} duration={500}>
434
    First line
435
  </Animatable.Text>
436
  <Animatable.Text animation="fadeInUp" delay={200} duration={500}>
437
    Second line
438
  </Animatable.Text>
439
  <Animatable.Text animation="fadeInUp" delay={400} duration={500}>
440
    Third line
441
  </Animatable.Text>
442
</View>
443
```