Home / animate / api

API Documentation

Animations

// Animate the fill color of an SVG circle
animate(ASTRO_ESCAPED_LEFT_CURLY_BRACKET
    target: "circle",
    fill: ["#80f", "#fc0"],
});

@okikio/animate creates animations by creating instances of the Animate class (a class that acts as a wrapper around the Web Animation API).

To create new instances of the Animate class, you can either import the Animate class and do this, new Animate(ASTRO_ESCAPED_LEFT_CURLY_BRACKET ... }) or import the animate (lowercase) method and do this, animate(ASTRO_ESCAPED_LEFT_CURLY_BRACKET ... }). The animate method creates new instances of the Animate class and passes the options it recieves as arguments to the Animate class.

import ASTRO_ESCAPED_LEFT_CURLY_BRACKET Animate, animate } from "@okikio/animate";

new Animate(ASTRO_ESCAPED_LEFT_CURLY_BRACKET
  target: [/* ... */],
  duration: 2000,
  // ... 
});

// or

animate(ASTRO_ESCAPED_LEFT_CURLY_BRACKET
  target: [/* ... */],
  duration: 2000,
  // ... 
});

Info: @okikio/animate lets you animate HTML and SVG elements with any CSS property that is animatable, you might be surprised to learn many CSS properties fall under this perview, including display and visibility.

The Animate class recieves a set of targets to animate, it then creates a list of Animation instances corrosponding to the respective target elements. In order to determine when all target animations are complete, the Animate class also creates a main Animation instance. The main Animation instance plays for the total duration of all target animations, and alerts the user when all target animations have completed.

Target animations are stored in Animate.prototype.animations: WeakMap<KeyframeEffect, Animation>, using their KeyframeEffect as the key, while the the main animation is stored in Animate.prototype.mainAnimation: Animation. You can actually access the animation for a specific target using Animate.prototype.getAnimation(target: HTMLElement): Animation, meaning you aren’t limited by what @okikio/animate provides, you can use the WAAPI api’s you know and love directly.

Note: Animation instances come from the Animation class of the Web Animations API. The Animation class represents a single animation player and provides playback controls and a timeline for an animation node or source, Read more…

Each property you animate needs an array defining the start and end values, or an Array of keyframes.

Info: Implicit to/from keyframes are now supported in all evergreen browsers, In newer browser versions, you are able to set a beginning or end state for an animation only (i.e. a single keyframe), and the browser will infer the other end of the animation if it is able to. Read more…

animate(ASTRO_ESCAPED_LEFT_CURLY_BRACKET
    target: ".div",
    transform: ["translate(0px)", "translate(1000px)"],
});

// Or
animate(ASTRO_ESCAPED_LEFT_CURLY_BRACKET
    target: ".div",
 
    // This is the same as ["translate(0px)", "translate(100px)"]
    keyframes: [
        ASTRO_ESCAPED_LEFT_CURLY_BRACKET transform: "translate(0px)" },
        ASTRO_ESCAPED_LEFT_CURLY_BRACKET transform: "translate(100px)" },
    ],
});

Note: you can only use one of these formats for an animation, and if Animate sees the keyframes property, it ignores all other css properties, in situations where Animate sees the keyframes property it will still accept animation properties like easing, duration, etc…

These value arrays can optionally be returned by an animation option method that takes the index of each element, the total number of elements, and each specific element, just like with other properties.

// First element translates by 100px, second element by 200px, etc.
animate(ASTRO_ESCAPED_LEFT_CURLY_BRACKET
    target: ".div",
    transform(index) ASTRO_ESCAPED_LEFT_CURLY_BRACKET
        return ["translate(0px)", `translate(${(index + 1) * 100}px)`];
    },
});

// Or
// Same as above
animate(ASTRO_ESCAPED_LEFT_CURLY_BRACKET
    target: ".div",
    keyframes(index) ASTRO_ESCAPED_LEFT_CURLY_BRACKET
        return [
            ASTRO_ESCAPED_LEFT_CURLY_BRACKET transform: "translate(0px)" },
            ASTRO_ESCAPED_LEFT_CURLY_BRACKET transform: `translate(${(index + 1) * 100}px)` },
        ];
    },
});

Animation Options

Animate supports many options ranging from target to fillMode, etc…, I highly suggest looking through the options offered as many of the features of @okikio/animate are unlocked when you know the options, and properly understand their quirks and abilities.

Read more about Animation Options →

Animation Options & CSS Properties as Methods

All options & properties except target, targets, autoplay, extend, onfinish, and options can be represented by a method with the arguments (index: number, total: number, element: HTMLElement)…

Read more about Animation Option Callback →

Transformable CSS Properties

By default WAAPI only supports string values with the unit specified for CSS properties to be animated, however, this is generally a bad Developer Experience, so, @okikio/animate does some computations on the given Animation Options, allowing you to use single value unitless numbers, strings, and arrays, as well as removing the need for the transform CSS property, as it exposes all the transform functions as CSS properties.

Learn more about Transformable CSS Properties →

Animation Progress and the requestAnimationFrame

The Web Animation API doesn’t allow for keeping track of the progress in a clean way, so, we are forced to use requestAnimationFrame to check the current progress of an animation, however, doing, so, can actually decrease framerates, so, I built a system to call requestAnimationFrame less often. If you listen for the update event on an Animate instance, you can get access to this custom framerate requestAnimationFrame, so, something like this,

import ASTRO_ESCAPED_LEFT_CURLY_BRACKET animate, Animate } from "@okikio/animate";
let animation = animate(ASTRO_ESCAPED_LEFT_CURLY_BRACKET /* ... */ });

// By default the "update" event will only run at 60 fps
animation.on("update", () => ASTRO_ESCAPED_LEFT_CURLY_BRACKET
    console.log("update")
});

// You can change the framerate by setting it using 
Animate.FRAME_RATE = 30; // 30 fps

Read through the request animation frame docs →

Promises and Promise-Like

new Animate() is promise-like meaning it has then, catch, and finally methods, but Animate itself isn’t a Promise (this is important to keep in mind when dealing with async/await asynchronous animations). Animate’s then resolves once all animations are complete. The promise resolves to an Array with the Animate instance being the only element.

Since Animate relies on native promises, you can benefit from all the usual features promises provide, such as Promise.all, Promise.race, and especially async/await which makes animation timelines easy to set up.

An interesting quirk of Promises is that even though Animate is not a Promise, async/await still work with it because it has a then, and catch.

Read through the promises doc to learn how to chain animations using promises.

Events

There are 8 events in total, they are:

  • “update”
  • “play”
  • “pause”
  • “begin”
  • “finish”
  • “cancel”
  • “error”
  • “stop”
  • “playstate-change”

The events themselves are fairly self explanitory, but to listen for said events you do this,

animation.on("play", () => ASTRO_ESCAPED_LEFT_CURLY_BRACKET
    // Do something
})

@okikio/animate uses @okikio/emitter, read through both @okikio/emitter’s doc and the events doc to properly learn how events work.

Custom Easing

Custom Easing is extra complex especially while using WAAPI, and ensuring great performance, but @okikio/animate is able to do it. The basic idea is to generate most of the numbers required for the custom easing, and then using WAAPI’s ability to linearly interpolate between numbers to do the rest. You can use custom easing like this,

import ASTRO_ESCAPED_LEFT_CURLY_BRACKET animate, CustomEasing } from "@okikio/animate"; 

animate(ASTRO_ESCAPED_LEFT_CURLY_BRACKET
    translateX: CustomEasing([0, 250], ASTRO_ESCAPED_LEFT_CURLY_BRACKET
        easing: "spring(5, 100, 10, 1)",

        // You can change the size of Array for the CustomEasing function to generate  
        numPoints: 200,

        // The number of decimal places to round, final values in the generated Array
        decimal: 5,
    }),

    easing: "linear"
})

Check out a demo of Custom Easing on Codepen →

This technique has some benefits and drawbacks, you can learn all about these on the custom easing doc.

Destroyable Animate

Remove elements and animations from the DOM when the .stop() method is called. Read more on the Destroyable Animate docs

AnimateAttributes & tweenAttr

Create morphing animations using the tweenAttr method, read more on the animate attributes doc.

Effects

Use pre-made effects in @okikio/animate, for example, the animate.css effects can be used via @shoelace-style/animations, read the effects doc, to learn more.

Stagger and Random

Queue Class

Methods & properties

Read through the methods and properties doc, to learn some of the most useful and importent methods and properties of Animate class.

Complete API Documentation

Not all available methods and properties are listed here (otherwise this README would be too long), go through the API documentation for the full documented API.