@pod-point/react-native-animatable
Version:
Easy to use declarative transitions and a standard set of animations for React Native
247 lines (171 loc) • 7.89 kB
Markdown
# react-native-animatable
Easy to use declarative transitions and a standard set of animations for React Native
## Installation
`$ npm install react-native-animatable --save`
## Usage
To animate things you must use the `createAnimatableComponent` composer similar to the `Animated.createAnimatedComponent`. The common components `View`, `Text` and `Image` are precomposed and exposed under the `Animatable` namespace. If you have your own component that you wish to animate, simply wrap it with a `Animatable.View` or compose it with:
```js
import * as Animatable from 'react-native-animatable';
MyCustomComponent = Animatable.createAnimatableComponent(MyCustomComponent);
```
### Declarative Usage
#### Predefined Animations
```html
<Animatable.Text animation="zoomInUp">Zoom me up, Scotty</Animatable.Text>
```
#### Looping
To make looping animations simply set the `iterationCount` to `infinite`. Most animations except the attention seekers work best when setting `direction` to `alternate`.
```html
<Animatable.Text animation="slideInDown" iterationCount={5} direction="alternate">Up and down you go</Animatable.Text>
<Animatable.Text animation="pulse" easing="ease-out" iterationCount="infinite" style={{ textAlign: 'center' }}>❤️</Animatable.Text>
```
#### Generic transitions
You can create your own simple transitions of a style property of your own choosing. The following example will increase the font size by 5 for every tap – all animated, all declarative! If you don't supply a `duration` property, a spring animation will be used.
*Note: If you are using colors, please use `rgba()` syntax.*
*Note: Transitions require `StyleSheet.flatten` available in React Native 0.15 or later. If you are running on anything lower, please polyfill as described under imperative usage.*
```html
<TouchableOpacity onPress={() => this.setState({fontSize: (this.state.fontSize || 10) + 5 })}>
<Animatable.Text transition="fontSize" style={{fontSize: this.state.fontSize || 10}}>Size me up, Scotty</Animatable.Text>
</TouchableOpacity>
```
#### Properties
*Note: Other properties will be passed down to underlying component.*
| Prop | Description | Default |
|---|---|---|
|**`animation`**|Name of the animation, see below for available animations. |*None*|
|**`duration`**|For how long the animation will run (milliseconds). |`1000`|
|**`delay`**|Optionally delay animation (milliseconds). |`0`|
|**`direction`**|Direction of animation, especially useful for repeating animations. Valid values: `normal`, `reverse`, `alternate`, `alternate-reverse`. |`normal`|
|**`easing`**|Timing function for the animation. Valid values: `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`. |`ease-in-out`|
|**`iterationCount`**|How many times to run the animation, use `infinite` for looped animations. |`1`|
|**`transition`**|What `style` property to transition, for example `opacity`, `rotate` or `fontSize`. Use array for multiple properties. |*None*|
|**`onAnimationBegin`**|A function that is called when the animation has been started. |*None*|
|**`onAnimationEnd`**|A function that is called when the animation has been completed successfully or cancelled. Function is called with an `endState` argument, refer to `endState.finished` to see if the animation completed or not. |*None*|
### Imperative Usage
#### Predefined Animations
All animations are exposed as functions on Animatable elements, they take an optional `duration` argument. They return a promise that is resolved when animation completes successfully or is cancelled.
```js
import * as Animatable from 'react-native-animatable';
class ExampleView extends Component {
render() {
return (
<TouchableWithoutFeedback onPress={() => this.refs.view.bounce(800).then((endState) => console.log(endState.finished ? 'bounce finished' : 'bounce cancelled');}>
<Animatable.View ref="view">
<Text>Bounce me!</Text>
</Animatable.View>
</TouchableWithoutFeedback>
);
}
}
```
To stop any ongoing animations, just invoke `stopAnimation()` on that element.
#### Generic transitions
##### `transition(fromValues, toValues[[, duration], easing])`
Will transition between given styles. If no `duration` or `easing` is passed a spring animation will be used.
##### `transitionTo(toValues[[, duration], easing])`
This function will try to determine the current styles and pass it along to `transition()` as `fromValues`.
```js
import * as Animatable from 'react-native-animatable';
class ExampleView extends Component {
render() {
return (
<TouchableWithoutFeedback onPress={() => this.refs.text.transitionTo({opacity: 0.2});}>
<Animatable.Text ref="text">Fade me!</Animatable.Text>
</TouchableWithoutFeedback>
);
}
}
```
## Demo / Example
See `Example` folder.
## Animations
Animations are heavily inspired by [Animated.css](https://daneden.github.io/animate.css/).
### Attention Seekers
* `bounce`
* `flash`
* `jello`
* `pulse`
* `rotate`
* `rubberBand`
* `shake`
* `swing`
* `tada`
* `wobble`
### Bouncing Entrances
* `bounceIn`
* `bounceInDown`
* `bounceInUp`
* `bounceInLeft`
* `bounceInRight`
### Bouncing Exits
* `bounceOut`
* `bounceOutDown`
* `bounceOutUp`
* `bounceOutLeft`
* `bounceOutRight`
### Fading Entrances
* `fadeIn`
* `fadeInDown`
* `fadeInDownBig`
* `fadeInUp`
* `fadeInUpBig`
* `fadeInLeft`
* `fadeInLeftBig`
* `fadeInRight`
* `fadeInRightBig`
### Fading Exits
* `fadeOut`
* `fadeOutDown`
* `fadeOutDownBig`
* `fadeOutUp`
* `fadeOutUpBig`
* `fadeOutLeft`
* `fadeOutLeftBig`
* `fadeOutRight`
* `fadeOutRightBig`
### Flippers
* `flipInX`
* `flipInY`
* `flipOutX`
* `flipOutY`
### Lightspeed
* `lightSpeedIn`
* `lightSpeedOut`
### Sliding Entrances
* `slideInDown`
* `slideInUp`
* `slideInLeft`
* `slideInRight`
### Sliding Exits
* `slideOutDown`
* `slideOutUp`
* `slideOutLeft`
* `slideOutRight`
### Zooming Entrances
* `zoomIn`
* `zoomInDown`
* `zoomInUp`
* `zoomInLeft`
* `zoomInRight`
### Zooming Exits
* `zoomOut`
* `zoomOutDown`
* `zoomOutUp`
* `zoomOutLeft`
* `zoomOutRight`
## [Changelog](https://github.com/oblador/react-native-animatable/releases)
## License
[MIT License](http://opensource.org/licenses/mit-license.html). © Joel Arvidsson 2015