README
@oframe/animate
@oframe/animate is a minimalistic javascript animation library written in es modules, made with creative WebGL production in mind. It mutates javascript objects, making it suitable for math, DOM and WebGL manipulation.
It doesn't do any magic CSS styling to reduce bloat, however it does have some advanced features, such as repeat, yoyo, stagger and async support. Plus it handles many of the pitfalls common in basic animation libraries (eg. animating multiple properties separately on an object, and automatically cancelling previous animations on a property).
Install
npm i @oframe/animate
Structure
The codebase is comprised of 2 files:
- Animation factory
- Easing function library
The total weight is 2kb when gzipped.
Usage
Import the Animate class in your project to get access to the API.
import { Animate } from './Animate.js';
To animate an object's properties, use the structure new Animate(object, duration, values)
. Duration is measured in milliseconds.
const obj = { x: 0 };
new Animate(obj, 1000, { x: 1 });
The other main animation options are ease
and delay
, which are implemented as per below. Refer to Easing.js
for the list of available ease equations.
new Animate(obj, 1000, {
x: 1,
ease: 'outQuint',
delay: 500,
});
If not declared, the default ease used is outCubic
. Use the Animate.setDefaultEase
method to change this globally for your project.
Animate.setDefaultEase('outQuint');
Update and complete callbacks can be implemented in two ways. Either declare update
and/or complete
in the values object as per below.
new Animate(obj, 1000, {
x: 1,
update: () => {/* ... */}),
complete: () => {/* ... */}),
});
or
Chain the returned animation object using the onUpdate
and/or onComplete
methods. Multiple callbacks can be added using this technique. And both techniques can be used in tandem.
new Animate(obj, 1000, { x: 1 })
.onUpdate(() => {/* ... */})
.onComplete(() => {/* ... */});
Promises are also avaible for async programming. Access the promise using the .promise()
method on the returned animation object.
await new Animate(obj, 1000, { x: 1 }).promise();
function() {/* ... */}
or
new Animate(obj, 1000, { x: 1 }).promise().then(() => {/* ... */});
To repeat an animation multiple times, the repeat
option is a number designating the amount of times to repeat. e.g. a value of 1
will play the animation twice - once as per usual, and once repeated. A value of -1
will repeat indefinitely. The repeatDelay
option designates an optional delay between each repeat.
new Animate(obj, 1000, {
x: 1,
repeat: 1,
repeatDelay: 500,
});
Used in tandem with the repeat
option, yoyo
is a boolean option flagging whether the animation should reverse the values for every second repeat. As well as reversing values, setting yoyo
to true
will also reverse the ease for every reverse animation. e.g. if the ease is outCubic
, on the reverse it will be inCubic
. Override this behaviour using the yoyoEase
value like below to set a specific ease for the reverse animations.
new Animate(obj, 1000, {
x: 1,
repeat: 1,
yoyo: true,
yoyoEase: 'outCubic',
});
Arrays of objects can also be animated all at once simply by passing in the array. Then use the stagger
option to assign a delay between each object's animation, which will be multiplied against their index in the array. A negative value will reverse the direction of the stagger, instead starting from last to first. Use the staggerComplete
option to add a callback to the last animation to finish.
const obj1 = { x: 0 };
const obj2 = { x: 0 };
new Animate([obj1, obj2], 1000, {
x: 1,
stagger: 20,
staggerComplete: () => {/* ... */}),
});
For more customisation, assign a function to the stagger
option that returns a number value. The arguments passed into the function are i
- the index of the object, and total
- the total number of objects in the array.
new Animate([obj1, obj2], 1000, {
x: 1,
stagger: (i, total) => Math.pow(i, 2) * 10,
});
Each object can support simultaneous animations on multiple properties. For example, the second animation on the y
property doesn't override the first on the x
property.
const obj = { x: 0, y: 1 };
new Animate(obj, 1000, { x: 1, ease: 'outQuint' });
new Animate(obj, 2000, { y: 0, ease: 'inQuint' });
Likewise, specific properties can be overridden without affecting the others. For example in the following, x
will still animate to 1
after 1000
ms, whereas y
will be overriden to animate to 2
after 2000
ms
new Animate(obj, 1000, { x: 1, y: 1 });
new Animate(obj, 2000, { y: 2 });
To stop specific animations, use the stop
method on the returned animation object.
const anim = new Animate(obj, 1000, { x: 1 });
anim.stop();
To clear all animations on an object, use the Animate.clear
method.
Animate.clear(obj)
String suffixes are supported, meaning that the suffix will be removed to calculate the animation, and reapplied on the output value.
const obj = { x: '50%' };
new Animate(obj, 1000, { x: '100%' });
Note: the target value doesn't need a suffix, and can just be a number - If the original value has a suffix, the output value will too.
const obj = { x: '50%' };
new Animate(obj, 1000, { x: 100 });
Users can finely tune the elastic eases. For inElastic
, outElastic
and/or inOutElastic
, users can pass in spring
and damping
values to change the defaults in the equation. The default values are spring = 1.0
, and damping = 0.4
.
new Animate(obj, 1000, {
x: 1,
ease: 'outElastic',
spring: 1.5,
damping: 0.8,
});