react-native-animatable-promise
v1.2.4
Published
Easy to use declarative transitions and animations for React Native
Downloads
10
Maintainers
Readme
react-native-animatable
Easy to use declarative transitions and a standard set of animations for React Native
Original project: https://github.com/oblador/react-native-animatable
What's new?
Added promise for functions 'transitionTo' and 'transition'. Now you can use them like that:
this.refs.objectRef.transitionTo({ opacity: 0 }).then(() => alert('Hey! Transition ends!'));
or:
this.refs.objectRef.transition({ opacity: 1 }, { opacity: 0 }).then(() => alert('Hey! Transition ends!'));
Installation
$ npm install react-native-animatable-promise --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:
import * as Animatable from 'react-native-animatable';
MyCustomComponent = Animatable.createAnimatableComponent(MyCustomComponent);
Declarative Usage
Animations
<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
.
<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.
<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: custom function or linear
, ease
, ease-in
, ease-out
, ease-in-out
, ease-in-cubic
, ease-out-cubic
, ease-in-out-cubic
, ease-in-circ
, ease-out-circ
, ease-in-out-circ
, ease-in-expo
, ease-out-expo
, ease-in-out-expo
, ease-in-quad
, ease-out-quad
, ease-in-out-quad
, ease-in-quart
, ease-out-quart
, ease-in-out-quart
, ease-in-quint
, ease-out-quint
, ease-in-out-quint
, ease-in-sine
, ease-out-sine
, ease-in-out-sine
, ease-in-back
, ease-out-back
, ease-in-out-back
. |ease
|
|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|
|useNativeDriver
|Whether to use native or JavaScript animation driver. Native driver can help with performance but cannot handle all types of styling and requires you to integrate that module on iOS. |false
|
Imperative Usage
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.
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
.
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>
);
}
}
Custom Animations
Animations can be referred to by a global name or a definition object.
Animation Definition Schema
An animation definition is a plain object that contains an optional easing
property, an optional style
property for static non-animated styles (useful for perspective
, backfaceVisibility
, zIndex
etc) and a list of keyframes. The keyframes are refered to by a number between 0 to 1 or from
and to
. Inspect the source in the definitions
folder to see more in depth examples.
A simple fade in animation:
const fadeIn = {
from: {
opacity: 0,
},
to: {
opacity: 1,
},
};
Combining multiple styles to create a zoom out animation:
const zoomOut = {
0: {
opacity: 1,
scale: 1,
},
0.5: {
opacity: 1,
scale: 0.3,
},
1: {
opacity: 0,
scale: 0,
},
};
To make your animations globally available by referring to them by a name, you can register them with initializeRegistryWithDefinitions
. This function can also be used to replace built in animations in case you want to tweak some value.
Animatable.initializeRegistryWithDefinitions({
myFancyAnimation: {
from: { ... },
to: { ... },
}
});
Demo / Example
See Example
folder.
Animations
Animations are heavily inspired by Animated.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
License
MIT License. © Joel Arvidsson 2015