@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 1000ms, whereas y will be overriden to animate to 2 after 2000ms

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,
});