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.