How I Used the WAAPI to Construct an Animation Library

No Comments

The Net Animations API lets us assemble animations and management their playback with JavaScript. The API opens the browser’s animation engine to builders and was designed to underlie implementations of each CSS animations and transitions, leaving the door open to future animation results. It is among the most performant methods to animate on the Net, letting the browser make its personal inside optimizations with out hacks, coercion, or window.requestAnimationFrame().

With the Net Animations API, we are able to transfer interactive animations from stylesheets to JavaScript, separating presentation from conduct. We now not must depend on DOM-heavy strategies resembling writing CSS properties and scoping lessons onto components to regulate playback course. And in contrast to pure, declarative CSS, JavaScript additionally lets us dynamically set values from properties to durations. For constructing customized animation libraries and creating interactive animations, the Net Animations API could be the right software for the job. Let’s see what it might probably do!

For the remainder of this text, I’ll generally seek advice from the Net Animation API as WAAPI. When trying to find assets on the Net Animation API, you could be led astray by looking “Net Animation API” so, to make it straightforward to search out assets, I really feel we should always undertake the time period WAAPI; inform me what you assume within the feedback under.

That is the library I made with the WAAPI

@okikio/animate is an animation library for the fashionable internet. It was impressed by animateplus, and animejs; it’s targeted on efficiency and developer expertise, and makes use of the Net Animation API to ship butter-smooth animations at a small measurement, weighing in at ~5.79 KB (minified and gzipped).

The story behind @okikio/animate

In 2020, I made a decision to make a extra environment friendly PJAX library, just like Rezo Zero’sBeginning Blocks challenge, however with the benefit of use of barbajs. I felt beginning blocks was simpler to increase with customized performance, and may very well be made smoother, quicker, and simpler to make use of.

Word: in case you don’t know what a PJAX library is I counsel trying out MoOx/pjax; briefly, PJAX permits for {smooth} transitions between pages utilizing fetch requests and switching out DOM Parts.

Over time my intent shifted, and I began noticing how usually websites from used PJAX, however usually butchered the pure expertise of the location and browser . Most of the websites appeared cool at first look, however the precise utilization usually advised a unique story — scrollbars had been usually overridden, prefetching was usually too keen, and a scarcity of preparation for individuals with out highly effective web connections, CPUs and/or GPUs. So, I made a decision to progressively improve the library I used to be going to construct. I began what I name the “native initiative” saved within the GitHub repo okikio/native; a method of introducing all of the cool and trendy options in a extremely performant, compliant, and light-weight means.

For the native initiative I designed the PJAX library @okikio/native; whereas testing on an precise challenge, I bumped into the Net Animation API, and realized there have been no libraries that took benefit of it, so, I developed @okikio/animate, to create a browser compliant animation library. (Word: this was in 2020, across the similar time use-web-animations by wellyshen was being developed. In case you are utilizing react and wish some fast animate.css like results, use-web-animations is an efficient match.) At first, it was presupposed to be easy wrapper however, little by little, I constructed on it and it’s now at 80% function parity with extra mature animation libraries.

Word: you possibly can learn extra on the native initiative in addition to the @okikio/native library on the Github repo okikio/native. Additionally, okikio/native, is a monorepo with @okikio/native and @okikio/animate being sub-packages inside it.

The place @okikio/animate suits into this text

The Net Animation API may be very open in design. It’s practical by itself nevertheless it’s not essentially the most developer-friendly or intuitive API, so I developed @okikio/animate to behave as a wrapper across the WAAPI and introduce the options you recognize and love from different extra mature animation libraries (with some new options included) to the high-performance nature of the Net Animation API. Give the challenge’s README a learn for way more context.

Now, let’s get began

@okikio/animate creates animations by creating new cases of Animate (a category that acts as a wrapper across the Net Animation API).

import { Animate } from”@okikio/animate”;

new Animate({
goal: [/* … */],
length: 2000,
// …

The Animate class receives a set of targets to animate, it then creates a listing of WAAPI Animation cases, alongside a fundamental animation (the primary animation is a small Animation occasion that’s set to animate over a non-visible component, it exists as a means of monitoring the progress of the animations of the varied goal components), the Animate class then performs every goal components Animation occasion, together with the primary animation, to create {smooth} animations.

The principle animation is there to make sure accuracy in several browser vendor implementations of WAAPI. The principle animation is saved in Animate.prototype.mainAnimation, whereas the goal component’s Animation cases are saved in a WeakMap, with the important thing being its KeyframeEffect. You possibly can entry the animation for a particular goal utilizing the Animate.prototype.getAnimation(el).

You don‘t want to completely perceive the prior sentences, however they’ll support your understanding of what @okikio/animate does. If you wish to study extra about how WAAPI works, try MDN, or if you need to study extra concerning the @okikio/animate library, I’d counsel trying out the okikio/native challenge on GitHub.

Utilization, examples and demos

By default, creating a brand new occasion of Animate may be very annoying, so, I created the animate operate, which creates new Animate cases each time it’s referred to as.

import animate from “@okikio/animate”;
// or
import { animate } from “@okikio/animate”;

goal: [/* … */],
length: 2000,
// …

When utilizing the @okikio/animate library to create animations you are able to do this:

import animate from “@okikio/animate”;

// Do that in case you put in it through the script tag: const { animate } = window.animate;

(async () => {
let [options] = await animate({
goal: “.div”,

// Items are added mechanically for rework CSS properties
translateX: [0, 300],
length: 2000, // In milliseconds
velocity: 2,

console.log(“The Animation is finished…”);

CodePen Embed Fallback

You too can play with a demo with playback controls:

CodePen Embed Fallback

Check out Movement Path:

CodePen Embed Fallback

Strive various kinds of Movement by altering the Animation Choices:

CodePen Embed Fallback

I additionally created a posh demo web page with polyfills:

Yow will discover the supply code for this demo within the animate.ts and animate.pug information within the GitHub repo. And, sure, the demo makes use of Pug, and is a reasonably complicated setup. I extremely counsel trying on the README as a primer for getting began.

The native initiative makes use of Gitpod, so if you wish to play with the demo, I like to recommend clicking the “Open in Gitpod” hyperlink because the complete setting is already arrange for you — there’s nothing to configure.

You too can try some extra examples on this CodePen assortment I put collectively. For essentially the most half, you possibly can port your code from animejs to @okikio/animate with few-to-no points.

I ought to most likely point out that @okikio/animate helps each the goal and targets key phrases for settings animation targets. @okikio/animate will merge each checklist of targets into one checklist and use Sets to take away any repeated targets. @okikio/animate helps features as animation choices, so you should use staggering just like animejs. (Word: the order of arguments are completely different, learn extra within the “Animation Choices & CSS Properties as Strategies” part of the README file.)

Restrictions and limitations

@okikio/animate isn’t good; nothing actually is, and seeing because the Net Animation API is a dwelling normal continually being improved, @okikio/animate itself nonetheless has a number of house to develop. That stated, I’m continually attempting to enhance it and would love your enter so please open a brand new challenge, create a pull request or we are able to have a dialogue over on the GitHub challenge.

The primary limitation is that it doesn’t actually have a built-in timeline. There are a number of causes for this:

I ran out of time. I’m nonetheless solely a scholar and don’t have a number of time to develop all of the initiatives I need to.I didn’t assume a proper timeline was wanted, as async/await programming was supported. Additionally, I added timelineOffset as an animation choice, ought to anybody ever must create one thing just like the timeline in animejs.I wished to make @okikio/animate as small as attainable.With group results and sequence results coming quickly, I believed it could be finest to go away the package deal small till an precise want comes up. On that be aware, I extremely counsel studying Daniel C. Wilson’s collection on the WAAPI, notably the fourth installment that covers group results and sequence results.

One other limitation of @okikio/animate is that it lacks help for customized easings, like spring, elastic, and so forth. However try Jake Archibald’s proposal for an easing worklet. He discusses a number of requirements which are presently in dialogue. I favor his proposal, because it’s the best to implement, to not point out essentially the most elegant of the bunch. In the mean time, I’m taking inspiration from Kirill Vasiltsov article on Spring animations with WAAPI and I’m planning to construct one thing comparable into the library.

The final limitation is that @okikio/animate solely helps automated items on rework features e.g. translateX, translate, scale, skew, and so forth. That is now not the case as of @okikio/animate@2.2.0, however there are nonetheless some limitations on CSS properties that help colour. Verify the GitHub launch for extra element.

For instance:

targets: [“.div”, document.querySelectorAll(“.el”)],

// By default “px”, might be utilized
translateX: 300,
left: 500,
margin: “56 70 8em 70%”,

// “deg” might be utilized to rotate as a substitute of px
rotate: 120,

// No items might be auto utilized
colour: “rgb(25, 25, 25)”,
“text-shadow”: “25px 5px 15px rgb(25, 25, 25)”

Seeking to the longer term

Some future options, like ScrollTimeline, are proper across the nook. I don’t assume anybody really is aware of when it should launch however because the ScrollTimeline in Chrome Canary 92, I believe it’s protected to say the possibilities of a launch within the close to future look fairly good.

I constructed the timeline animation choice into @okikio/animate to future-proof it. Right here’s an instance:

CodePen Embed Fallback

Because of Bramus for the demo inspiration! Additionally, it’s possible you’ll want the Canary model of Chrome or must activate Experimental Net Platform options in Chrome Flags to view this demo. It appears to work simply high-quality on Firefox, although, so… 🤣.

If you wish to learn extra on the ScrollTimeline, Bramus wrote a superb article on it. I might additionally counsel studying the Google Builders article on Animation Worklets.

My hope is to make the library smaller. It’s presently ~5.79 KB which appears excessive, no less than to me. Usually, I might use a bundlephobia embed however that has hassle bundling the challenge, so if you wish to confirm the scale, I counsel utilizing as a result of it really bundles the code domestically in your browser. I particularly constructed it for checking the bundle measurement of @okikio/animate, however be aware it’s not as correct as bundlephobia.


One of many earlier demos exhibits polyfills in motion. You will want web-animations-next.min.js from web-animations-js to help timelines. Different trendy options the KeyframeEffect constructor is required.

The polyfill makes use of JavaScript to check if the KeyframeEffect is supported and, if it isn’t, the polyfill hundreds and does its factor. Simply keep away from including async/defer to the polyfill, or it won’t work the best way you count on. You’ll additionally need to polyfill Map, Set, and Promise.

<!– Async –>
<script src=”,es2015,es2018,Array.prototype.consists of,Map,Set,Promise” async></script>
<!– NO Async/Defer –>
<script src=”./js/webanimation-polyfill.min.js”></script>
<!– Content material –>

And in case you’re constructing for ES6+, I extremely suggest utilizing esbuild for transpiling, bundling, and minifying. For ES5, I counsel utilizing esbuild (with minify off), Typescript (with goal of ES5), and terser; as of now, that is the quickest setup to transpile to ES5, it’s quicker and extra dependable than babel. See the Gulpfile from the demo for extra particulars.


@okikio/animate is a wrapper across the Net Animation API (WAAPI) that lets you use all of the options you like from animejs and different animation libraries, in a small and concise package deal. So, what are your ideas after studying about it? Is it one thing you assume you’ll attain for when you must craft complicated animations? Or, much more vital, is there one thing that may maintain you again from utilizing it? Go away a remark under or be a part of the dialogue on Github Discussions.

This text initially appeared on, it additionally appeared on and
Picture by Pankaj Patel on Unsplash.

The publish How I Used the WAAPI to Construct an Animation Library appeared first on CSS-Tips.

You possibly can help CSS-Tips by being an MVP Supporter.

    About Marketing Solution Australia

    We are a digital marketing company with a focus on helping our customers achieve great results across several key areas.

    Request a free quote

    We offer professional SEO services that help websites increase their organic search score drastically in order to compete for the highest rankings even when it comes to highly competitive keywords.

    Subscribe to our newsletter!

    More from our blog

    See all posts

    Leave a Comment