Introducing the JavaScriptWeb Animations API

The JavaScript Web Animations API is a new API that lets us create animations with JavaScript by manipulating the elements that we want to animate.

In this article, we’ll look at how to create simple animations with the API.

Basic Usage

The way we create the animation is similar to how we do it with CSS. We specify how the element animates by specifying how we transform the element in keyframes. The only difference is that we do it with JavaScript instead of CSS.

To animate an element, we call the animate method on the element with 2 arguments. The first argument is an array with the keyframe for each entry. Each keyframe object has the styles to apply when the keyframe is displayed.

The second object is the timing object, which has the duration and iterations properties. duration is the number of milliseconds to animate the element. The iteration is the number of iterations to run the animation for. It can be a positive number of Infinity .

For instance, we can write the following HTML and JavaScript to animate an object:

HTML:

<img src='https://interactive-examples.mdn.mozilla.net/media/examples/grapefruit-slice-332-332.jpg' width=100 height=100>

JavaScript:

const action = [{
    transform: 'rotate(0) translate3D(-50%, -50%, 0)',
    color: '#000'
  },
  {
    color: '#431236',
    offset: 0.3
  },
  {
    transform: 'rotate(360deg) translate3D(-50%, -50%, 0)',
    color: '#000'
  }
];

const timing = {
  duration: 3000,
  iterations: Infinity
}

document.querySelector("img").animate(
  action,
  timing
)

The action array has the keyframe styles and the timing object has the duration and the number of iterations of the animation to run.

Then we should see an image that rotates forever.

Controlling playback with play(), pause(), reverse(), and playbackRate

The animate method returns an object with the play , pause and reverse methods. playbackRate is a numerical property that can be set by us. A negative playback rate means the animation plays in reverse.

For instance, we can add buttons to call these methods as follows. First, we add the following HTML code to add buttons for the playing, pausing, and reversing, and also a range slider for changing the playback rate:

<button id='play'>Play</button>
<button id='pause'>Pause</button>
<button id='reverse'>Reverse</button>
<input type='range' min='-2' max='2'>

<img src='https://interactive-examples.mdn.mozilla.net/media/examples/grapefruit-slice-332-332.jpg' width=100 height=100>

Then we add some CSS to move the image:

img {
  position: relative;
  top: 100px;
  left: 100px;
}

Finally, we add the JavaScript for the animation and event handler for the buttons and input that call the methods and set the playbackRate property as follows:

const action = [{
    transform: 'rotate(0) translate3D(-50%, -50%, 0)',
    color: '#000'
  },
  {
    color: '#431236',
    offset: 0.3
  },
  {
    transform: 'rotate(360deg) translate3D(-50%, -50%, 0)',
    color: '#000'
  }
];

const timing = {
  duration: 3000,
  iterations: Infinity
}

const animation = document.querySelector("img").animate(
  action,
  timing
)

const play = document.getElementById('play');
const pause = document.getElementById('pause');
const reverse = document.getElementById('reverse');
const range = document.querySelector('input');

play.onclick = () => animation.play();
pause.onclick = () => animation.pause();
reverse.onclick = () => animation.reverse();
range.onchange = () => {
  const val = range.value;
  animation.playbackRate = +val;
}

In the code above, we added the buttons. Then in the JavaScript, we have:

const play = document.getElementById('play');
const pause = document.getElementById('pause');
const reverse = document.getElementById('reverse');
const range = document.querySelector('input');

play.onclick = () => animation.play();
pause.onclick = () => animation.pause();
reverse.onclick = () => animation.reverse();
range.onchange = () => {
  const val = range.value;
  animation.playbackRate = +val;
}

to call the methods and set the properties on animation , which is assigned to the animation object that’s returned by animate .

Then we can do whatever action is indicated by the method’s names and also set the playback rate when we move the slider.

Getting Information Out of Animations

We can also get more information out of the animation object, like the duration and the current time of the animation.

We can get all that information from the animation object in the code above. In Chrome, we have the startTime and currentTime to get the start time and current time of the animation respectively.

It also has the playState and playbackRate . The properties of the animation object may differ between browsers.

Conclusion

We can create simple animations with the Web Animations API. It’s a simple API that lets us define keyframes for animation as we do with CSS animations.

The only difference is that we can do more things like changing the playback rate, and controlling the playback of the animation with play, pause, and reverse.