UI Development

Web Animations API – WAAPI


We have plenty ways to animate things on the web. We generally use CSS or maybe some external libraries. But each method comes with some pros and cons.
Web APIs are always evolving. Some are well implemented while others are still being defined by regularly updating their spec. One of the Web APIs is the Web Animations API also known as WAAPI. The  Web animations API is relatively new and the initial version of the spec was published in 2012 whereas the API was first implemented in 2014

It allows to manipulate the CSS animations through javascript. The syntax is similar to CSS animations though but it has additional features to make the creation and manipulation of animations much more easier. This API was designed to use the implementations of CSS animations and CSS transitions, letting the browser to make its own internal optimizations that can move interactive animations from stylesheets to javascript. We don’t need DOM-heavy techniques or css properties or classes to control playback directions. Lets see what WAAPI can do!!

Web Animations Interfaces:

  1. Animation – It provides the playback control and timeline for an animation
  2. KeyframeEffect – It describes the properties of animations and values which are called as keyframes and their timing options
  3. AnimationTimeline – It is used to represent the timeline features. It cannot be directly used and hence we have to use DocumentTimeline instead
  4. AnimationEvent – It provides the information related to animation events
  5. DocumentTimelineIt is used to represent the the timeline features. Used instead of AnimationTimeline
  6. EffectTiming – This property is optional and it represents the timing properties for animation effects. Without setting the duration, the animation will not work here
  7. Element.animate() – It creates the new animation to the element

    var elementAnimation = element.animate(keyframes, options);
  8. Element.getAnimations() – It returns an array of all animation objects

    const elementAnimations = Element.getAnimations(options);

Animating with the Web Animations API:

  1. Here’s a simple cube rotating example via CSS:
    Link to Codepen: https://codepen.io/nikitha_golla/pen/mdJabMe

      width: 100px;
      height: 100px;
      margin: 10% 50%;
      background-color: yellow;
      border-radius: 20px;
      animation: rotateCube 1s infinite;
      animation-timing-function: linear;
    @keyframes rotateCube{
        transform: rotate(0deg);
      60% {
        background-color: green;
        transform: rotate(180deg);

    Let’s see how we can recreate the same thing using web animations API:
    We need to a keyframe object that has same information in CSS keyframes.

    var cubeRotating = [{
    	transform: 'rotate(0deg)',
    	backgroundColor: 'yellow'
    }, {
    	backgroundColor: 'green',
    	offset: 0.3
    }, {
    	transform: 'rotate(180deg)',
    	backgroundColor: 'yellow'

    We do not need to add the percentage of time at which each steps executes. The WAAPI will automatically divide the animation in equal parts based on number of keys, however we wanted to change the color at 30% of the way so we add an offset property of 0.3

    We then create an object to represent timing properties of our cube

    var cubeTiming = {
    	duration: 1000,
    	iterations: Infinity

    Finally, to trigger the animation we use element.animate()

    var cubeAnimation = document.getElementById('rotating-cube')
        .animate(cubeRotating, cubeTiming)

    Link to Codepen: https://codepen.io/nikitha_golla/pen/QWbzjbx


  2. WAAPI has the most powerful feature to control the animation playback. Let’s checkout how to start and stop the animation:
    cubeAnimation.pause(); //pauses the animation
    cubeAnimation.play();  //plays the paused animation

    We also have other methods like finish(), cancel() and reverse()
    a. animation.finish(): It sets the current playback time to the end of the animation
    b. animation.cancel(): It clears all the keyframe effects and aborts the animation
    c. animation.reverse(): It reverses the playback direction. If its called on unplayed animation, the animation plays backwards. If its called on a paused animation, the animation will continue in reverse
    d. animation.playbackRate: It sets or returns the playback rate that provides the scaling factor from rate of change to current factor

    var currentPlaybackRate = Animation.playbackRate;
    Animation.playbackRate = newRate;

    We can modify the speed of the animation by changing the playback rate

    document.body.onclick = () => {
    	cubeAnimation.playbackRate *= 1.5;

    Link to Codepen: https://codepen.io/nikitha_golla/pen/bGdOEVy


Performance and Browser Compatibility:

WAAPI provides the same performance improvements as that of CSS animations. But if we are sequencing things and those depends on specific timings, then Web animations API is useful. If we cannot hardcode the animations in CSS or maybe any property depends on the input of user, we use api instead of CSS animations. In other words, if we are implementing any complex animations for example a game then we would definitely prefer WAAPI.
The Web Animations API is still at experimental stage so it merely works with the latest versions of Chrome and Firefox. Yet there are some features which are partially supported like getAnimations. In such case, we will be using a polyfill available for browsers that don’t support the API yet

Links for reference:

About The Author