unanime.js
Getting started
Download
$ npm install unanime --save
Import
ES6 modules
import { animate } from 'unanime';
Common js
const animate = require('unanime');
Quick start
Example
import { animate } from 'unanime';
const myAnimation = animate(
'.targets',
[
{transform: 'translateX(100px)'}
],
{
duration: 1500,
direction: 'alternate',
iterations: 3,
autoplay: true
}
)
Structure
cont var = animate(
// Targets,
[
// Keyframes
],
{
// Options
}
)
Targets
String, Object or Array accepted.
// Targets
'.myTargets' // Under the hood, document.querySelectorAll is used
Keyframes
Array with one or multiple objects. When one object is specified, it's like 'TO' direction. Use all CSS(Js) property you want.
// Keyframes
[
{transform: 'translate3d(0, 0, 0)', backgroundColor: 'red'},
{transform: 'translate3d(0, 100px, 0)', backgroundColor: 'green'},
]
Options
Set your options, they all have a default value specified. You can use an anonymous function on every property.
// Options
{
duration: () => Math.floor(Math.random() * 10000); // 5683
}
const anotherTarget = document.querySelector('#anotherTarget');
// Inject in var for timeline usage
const myAnimation = animate(
// Targets (string, object or array)
['.targets', anotherTarget],
// Keyframes (array)
[
{transform: 'translate3d(0, 0, 0)', backgroundColor: 'red'},
{transform: 'translate3d(0, 100px, 0)', backgroundColor: 'green'},
],
// Options (object)
{
duration: 1000,
// animation's duration in ms (number, object) | default: 1000
direction: 'normal',
// 'normal', 'reverse', 'alternate' (string) | default: 'normal'
easing: 'easeOutBack',
// easings.net accepted, basic css or cubic-bezier (string) | default: 'linear'
delay: 200,
// delay before animation start (number, object) | default: 0
endDelay: 0,
// delay after animation finished (number, object) | default: 0
iterations: 3,
// times the animation is executed (positive number or Infinity) | default: 1
iterationStart: 1.2,
// select at which iteration animation start (number) | default: 0
fill: 'both',
// apply the style to your targets 'none', 'auto', 'backwards', 'forwards', 'both' (string) | default: 'both'
composite: 'replace',
// choose how each keyframe impact the style, 'replace', 'add', 'accumulate' | default: 'replace'
playbackRate: 1,
// choose the speed of your animation without changing duration (+ / - number) | default: 1
autoplay: false,
// start animation when ready (boolean) | default: false
initStyles: true,
// option that apply css style (first keyframes) to the target | default: false
commitStyles: false,
// option that apply css style to targets after animation finished | default: false
autocancel: false,
// remove animation from browser at the end | default: false
willChange: false,
// add and remove automatically a 'will-change: transform' to your target during animation | default: false
}
)
myAnimation.play();
Running
Animation is not running by default, you have three options:
// Options
{ autoplay: true }
or
// Method
myAnimation.play();
or
// Timeline
const tl = timeline(
[
{animate: myAnimation}
]
)
tl.play();
Methods
Player
.play()
Start the animation.
.reverse()
Reverse the current playbackRate and play animation.
.pause()
Pause the animation.
.reset()
Go back to first frame and pause animation.
.restart()
Go back to first frame and play animation.
.finish()
Go to the last frame animation.
.cancel()
Stop and remove animation from browser.
.seek(number)
Go to a specific moment of animation (number from 0 to 1).
Example:
myAnimation.play();
setTimeout(() => {
myAnimation.pause();
}, 2500);
Getters
.getDuration()
Return the total duration with duration, delays, iterations ...
.getCurrentIteration()
Return the current iteration when executed.
.getPlayState()
Return the animation's status: 'idle', 'running', 'finished'.
.getPlaybackRate()
Return the current playbackRate.
.getProgress() // Soon
Return the current progression (from 0 to 1).
Example:
myAnimation.getPlayState();
// 'running'
Setters
.setDirection(string)
Set a new direction ('normal', 'reverse', 'alternate').
.setPlaybackRate(number)
Set a new playbackRate ( + / - number). Change the speed of animation.
.setWillChange(boolean)
Set the option willChange to true or false.
.setInitStyles(boolean)
Set the option initStyles to true or false.
.setCommitStyles(boolean)
Set the option commitStyles to true or false.
Example:
myAnimation.setDirection('alternate');
Events
.onready()
Execute when animation is ready.
.onplay()
Execute when animation is playing.
.onpause()
Execute when animation is paused.
.onfinish()
Execute when animation is finished.
.onremove()
Execute when animation is removed (everytime the animation is paused/play or changed);
.oncancel()
Execute when animation is canceled.
Example:
myAnimation.onready(() => {
console.log('Ready to play !');
});
Stagger
Staggering allows you to animate multiple elements with follow through and overlapping action.
Example:
// Options
{delay: {stagger: 100, from: 'center', direction: 'normal'}}
Structure
// Options
{ yourOption: {
default: 0, // initial value of your option added to stagger | default: option's default
stagger: 100, // amount that will be multiplied by array index (number) | default: 0
from: 3, // choose the starting point of your stagger propagation (string, number, array) | default: 'start'
direction: 'reverse' // select the way stagger in computed (string) | default: 'normal'
}
}
from:
There are different ways to set 'from' option in stagger object.
'start', 'center', 'end' // select one mode
or
10 // select array index(+1)
or
[2, 7, 13] // select multiple starting points
direction:
Select the propagation's direction.
'normal' // default
or
'reverse'
Stagger can be used on every options property who takes a number. Example:
// Options
{
delay: {stagger: 200},
duration: {default: 2500, stagger: 100},
iterations: {default: 4, stagger: 0.05},
iterationStart: {default: 1, stagger: 0.02},
playbackRate: {default: 1, stagger: 0.05},
...
}
Easing stagger
Easing can accept an array to set different easing on each elements of your targets. You can directly use this list of easing as string.
// Options
{
easing: ['easeInCirc', null, 'ease-out', 'cubic-bezier(.17,.67,.83,.67)']
// if null, get previous easing
}
Timeline
import { animate, timeline } from 'unanime';
const tl = timeline(
// Animations list
[
{ animate: myAnimation1},
{ animate: myAnimation2, start: '<+800'},
],
// Timeline options
{autoplay: false, iterations: Infinity, direction: 'alternate'}
)
tl.play();
Animation start
You can change the start point of each animations within the timeline by adding 'start'.
Relative position
Use STRING to change the relative position of your animation.
{animate: myAnimation1, start: '+200'}, // +200ms from the relative start
{animate: myAnimation2, start: '-600'},
{animate: myAnimation3, start: '<'}, // start with the previous animation
{animate: myAnimation4, start: '<<<'}, // previous * 3 (myAnimation1)
{animate: myAnimation5, start: '<<+800'},
{animate: myAnimation6, start: '<-1200'}
Absolute position
Use NUMBER to change the absolute position of your animation.
{animate: myAnimation2, start: 6500} // start at 6500ms after the timeline started