0
# React Native Animatable
1
2
React Native Animatable provides easy-to-use declarative transitions and animations for React Native applications. It offers a comprehensive set of pre-built animations, custom animation creation capabilities, and both declarative and imperative animation APIs with full TypeScript support.
3
4
## Package Information
5
6
- **Package Name**: react-native-animatable
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install react-native-animatable --save`
10
11
## Core Imports
12
13
```javascript
14
import * as Animatable from 'react-native-animatable';
15
```
16
17
ES6 destructuring:
18
19
```javascript
20
import { View, Text, Image, createAnimatableComponent } from 'react-native-animatable';
21
```
22
23
CommonJS:
24
25
```javascript
26
const Animatable = require('react-native-animatable');
27
```
28
29
## Basic Usage
30
31
```javascript
32
import * as Animatable from 'react-native-animatable';
33
34
// Declarative animation with pre-built animation
35
<Animatable.Text animation="zoomInUp" duration={1000}>
36
Zoom me up, Scotty
37
</Animatable.Text>
38
39
// Custom animatable component
40
const AnimatedButton = Animatable.createAnimatableComponent(TouchableOpacity);
41
42
// Imperative animation with refs
43
class MyComponent extends Component {
44
handleViewRef = ref => this.view = ref;
45
46
bounce = () => {
47
this.view.bounce(800).then(endState =>
48
console.log(endState.finished ? 'bounce finished' : 'bounce cancelled')
49
);
50
};
51
52
render() {
53
return (
54
<TouchableWithoutFeedback onPress={this.bounce}>
55
<Animatable.View ref={this.handleViewRef}>
56
<Text>Bounce me!</Text>
57
</Animatable.View>
58
</TouchableWithoutFeedback>
59
);
60
}
61
}
62
```
63
64
## Architecture
65
66
React Native Animatable is built around several key components:
67
68
- **Pre-built Components**: `View`, `Text`, and `Image` components with animation capabilities built-in
69
- **Component Factory**: `createAnimatableComponent` HOC for making any React Native component animatable
70
- **Animation System**: 50+ built-in animations organized into 11 categories (attention seekers, entrances, exits, etc.)
71
- **Custom Animations**: `createAnimation` for defining custom keyframe-based animations
72
- **Animation Registry**: Global registry system for registering and reusing named animations
73
- **Easing Functions**: 23 built-in easing functions plus support for custom easing
74
- **Dual API**: Both declarative (props-based) and imperative (method-based) animation control
75
76
## Capabilities
77
78
### Pre-built Components
79
80
Ready-to-use animated versions of core React Native components with full animation support.
81
82
```javascript { .api }
83
const View: AnimatableComponent<ViewProps, ViewStyle>;
84
const Text: AnimatableComponent<TextProps, TextStyle>;
85
const Image: AnimatableComponent<ImageProps, ImageStyle>;
86
```
87
88
[Pre-built Components](./prebuilt-components.md)
89
90
### Component Creation
91
92
Create animatable versions of any React Native component using the higher-order component factory.
93
94
```javascript { .api }
95
function createAnimatableComponent<P, S>(
96
Component: ComponentClass<P> | FunctionComponent<P>
97
): AnimatableComponent<P, S>;
98
```
99
100
[Component Creation](./component-creation.md)
101
102
### Built-in Animations
103
104
Comprehensive collection of 50+ pre-built animations across 11 categories, inspired by Animate.css.
105
106
```javascript { .api }
107
type Animation =
108
| 'bounce' | 'flash' | 'jello' | 'pulse' | 'rotate' | 'rubberBand' | 'shake' | 'swing' | 'tada' | 'wobble'
109
| 'bounceIn' | 'bounceInDown' | 'bounceInUp' | 'bounceInLeft' | 'bounceInRight'
110
| 'bounceOut' | 'bounceOutDown' | 'bounceOutUp' | 'bounceOutLeft' | 'bounceOutRight'
111
| 'fadeIn' | 'fadeInDown' | 'fadeInDownBig' | 'fadeInUp' | 'fadeInUpBig'
112
| 'fadeInLeft' | 'fadeInLeftBig' | 'fadeInRight' | 'fadeInRightBig'
113
| 'fadeOut' | 'fadeOutDown' | 'fadeOutDownBig' | 'fadeOutUp' | 'fadeOutUpBig'
114
| 'fadeOutLeft' | 'fadeOutLeftBig' | 'fadeOutRight' | 'fadeOutRightBig'
115
| 'flipInX' | 'flipInY' | 'flipOutX' | 'flipOutY'
116
| 'lightSpeedIn' | 'lightSpeedOut'
117
| 'slideInDown' | 'slideInUp' | 'slideInLeft' | 'slideInRight'
118
| 'slideOutDown' | 'slideOutUp' | 'slideOutLeft' | 'slideOutRight'
119
| 'zoomIn' | 'zoomInDown' | 'zoomInUp' | 'zoomInLeft' | 'zoomInRight'
120
| 'zoomOut' | 'zoomOutDown' | 'zoomOutUp' | 'zoomOutLeft' | 'zoomOutRight';
121
```
122
123
[Built-in Animations](./builtin-animations.md)
124
125
### Custom Animations
126
127
Create custom keyframe-based animations with full control over timing and styling.
128
129
```javascript { .api }
130
function createAnimation(definition: CustomAnimation): object;
131
132
interface CustomAnimation {
133
from?: StyleObject;
134
to?: StyleObject;
135
style?: StyleObject;
136
easing?: Easing;
137
[progress: number]: StyleObject;
138
}
139
```
140
141
[Custom Animations](./custom-animations.md)
142
143
### Animation Registry
144
145
Global registry system for registering, managing, and reusing named animations across your application.
146
147
```javascript { .api }
148
function registerAnimation(name: string, animation: CustomAnimation): void;
149
function initializeRegistryWithDefinitions(animations: { [key: string]: CustomAnimation }): void;
150
```
151
152
[Animation Registry](./animation-registry.md)
153
154
### Declarative Animation
155
156
Props-based animation control with extensive configuration options for timing, easing, and behavior.
157
158
```javascript { .api }
159
interface AnimatableProps {
160
animation?: Animation | string | CustomAnimation;
161
duration?: number;
162
delay?: number;
163
direction?: 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
164
easing?: Easing;
165
iterationCount?: number | 'infinite';
166
iterationDelay?: number;
167
transition?: string | string[];
168
useNativeDriver?: boolean;
169
isInteraction?: boolean;
170
onAnimationBegin?: () => void;
171
onAnimationEnd?: (endState: { finished: boolean }) => void;
172
onTransitionBegin?: (property: string) => void;
173
onTransitionEnd?: (property: string) => void;
174
}
175
```
176
177
[Declarative Animation](./declarative-animation.md)
178
179
### Imperative Animation
180
181
Method-based animation control for complex programmatic animations and transitions.
182
183
```javascript { .api }
184
interface AnimatableComponent {
185
animate(animation: Animation | CustomAnimation, duration?: number, iterationDelay?: number): Promise<{ finished: boolean }>;
186
stopAnimation(): void;
187
transition(fromValues: object, toValues: object, duration?: number, easing?: Easing): void;
188
transitionTo(toValues: object, duration?: number, easing?: Easing): void;
189
[animationName: string]: (duration?: number) => Promise<{ finished: boolean }>;
190
}
191
```
192
193
[Imperative Animation](./imperative-animation.md)
194
195
## Types
196
197
```javascript { .api }
198
type Easing =
199
| 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out'
200
| 'ease-in-cubic' | 'ease-out-cubic' | 'ease-in-out-cubic'
201
| 'ease-in-circ' | 'ease-out-circ' | 'ease-in-out-circ'
202
| 'ease-in-expo' | 'ease-out-expo' | 'ease-in-out-expo'
203
| 'ease-in-quad' | 'ease-out-quad' | 'ease-in-out-quad'
204
| 'ease-in-quart' | 'ease-out-quart' | 'ease-in-out-quart'
205
| 'ease-in-quint' | 'ease-out-quint' | 'ease-in-out-quint'
206
| 'ease-in-sine' | 'ease-out-sine' | 'ease-in-out-sine'
207
| 'ease-in-back' | 'ease-out-back' | 'ease-in-out-back'
208
| ((t: number) => number);
209
210
type Direction = 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
211
212
interface AnimatableComponent<P, S> extends NativeMethods {
213
animate(animation: Animation | CustomAnimation, duration?: number, iterationDelay?: number): Promise<{ finished: boolean }>;
214
stopAnimation(): void;
215
transition(fromValues: S, toValues: S, duration?: number, easing?: Easing): void;
216
transitionTo(toValues: S, duration?: number, easing?: Easing): void;
217
setNativeProps(nativeProps: object): void;
218
[K in Animation]: (duration?: number) => Promise<{ finished: boolean }>;
219
}
220
```