Animation with JavaScript

Smooth motion, one frame at a time

An animation is a picture that changes a little at a time, many times a second. On a web page, JavaScript can slide a box, fade in a panel, or move a game character.

The browser draws the page on the screen again and again. Each new drawing is called a repaint, and one drawing is called a frame. Good animation code does three things:

• It changes the picture just before the browser draws the next frame.
• It measures how much time really passed, instead of guessing.
• It moves less for people who ask their device for less motion.

This lesson starts with requestAnimationFrame, the tool for the first two. Then it covers timing functions, how to choose between CSS and JavaScript, and element.animate().

In the Timers lesson you met setInterval. It runs your code every few milliseconds, on its own clock. It does not know when the browser is about to draw. For motion, you want to ask two other questions:

• Is the browser ready to draw the next frame?
• How much time has passed since the last frame?

requestAnimationFrame(callback) asks the browser: "Run this function once, just before the next repaint." A callback is a function you hand over so that someone else can call it later. People often shorten requestAnimationFrame to rAF.

The browser passes one number to your callback: a timestamp. It is the time of this frame, in milliseconds (thousandths of a second). Every rAF callback in the same frame gets the same timestamp, so two animations on one page stay in step.

How often does a frame come? That depends on the screen. Many screens draw 60 frames a second. Others draw 90, 120, or a number that changes. In a hidden browser tab, frames may slow down or stop.

1let rafId;2let previous;3let position = 0;4const speed = 0.12; // pixels per millisecond5 6function frame(timestamp) {7  const elapsed = previous === undefined ? 0 : timestamp - previous;8  previous = timestamp;9  position += speed * elapsed;10  dot.style.transform = `translateX(${position}px)`;11  rafId = requestAnimationFrame(frame);12}13 14rafId = requestAnimationFrame(frame);15// Later: cancelAnimationFrame(rafId);

Line by line:

1. Lines 1 to 4 make four variables. rafId keeps the request number. previous keeps the last timestamp. position is where the dot is. speed is 0.12 pixels per millisecond.
2. Line 6 starts the frame function. The browser calls it with the timestamp.
3. Line 7 works out elapsed: the time since the last frame. On the very first frame there is no last frame, so it uses 0.
4. Line 8 saves this timestamp for the next frame.
5. Line 9 adds speed times elapsed time to the position.
6. Line 10 moves the dot on the screen with a CSS transform.
7. Line 11 asks for the next frame. This is what makes it a loop.
8. Line 14 asks for the very first frame. Line 15 is a note: later, cancelAnimationFrame(rafId) stops the loop.

The most important line is line 7, the elapsed time. You could move the dot a fixed amount every frame, like 2 pixels. But then the speed depends on the screen: a screen with 120 frames a second moves the dot twice as fast as one with 60. With elapsed time, the speed is set in pixels per millisecond. If a frame comes late, the dot moves farther in that frame, so it stays on time.

const startedAt = 1000;
const now = 1300;
const duration = 1000;
const progress = progressFraction(startedAt, now, duration);
bar.style.transform = `scaleX(${progress})`;
console.log(`${Math.round(progress * 100)}%`);

This example uses fixed times, so it prints the same thing every time. progressFraction is a small helper this lesson provides. It works out (now − start) ÷ duration and keeps the answer between 0 and 1.

1. Lines 1 to 3: the task started at 1,000 ms, it is now 1,300 ms, and the task takes 1,000 ms.
2. Line 4: 300 ms out of 1,000 ms have passed, so progress is 0.3.
3. Line 5 stretches the bar to 30% of its full width with scaleX(0.3).
4. Line 6 prints 30%.

On a real page, a rAF loop would give you a new "now" on every frame, and the bar would grow as time passes.

1let rafId;2let previous;3let position = 0;4const speed = 0.12; // pixels per millisecond5 6function frame(timestamp) {7  const elapsed = previous === undefined ? 0 : timestamp - previous;8  previous = timestamp;9  position += speed * elapsed;10  dot.style.transform = `translateX(${position}px)`;11  rafId = requestAnimationFrame(frame);12}13 14rafId = requestAnimationFrame(frame);15// Later: cancelAnimationFrame(rafId);

The lab does not start moving when the page loads. Real pages should do the same, unless the motion is needed and safe. Let the reader press a button to start.

requestAnimationFrame returns a number called the request id. Always keep it. To stop the loop, pass it to cancelAnimationFrame(id). Do this when the reader pauses or resets, and when that part of the page is removed.

function pauseWhenHidden() {
  if (document.hidden && rafId !== undefined) {
    cancelAnimationFrame(rafId);
    rafId = undefined;
    previous = undefined;
  } else if (!document.hidden && rafId === undefined) {
    rafId = requestAnimationFrame(frame);
  }
}

document.addEventListener("visibilitychange", pauseWhenHidden);

Line by line:

1. Line 11 runs pauseWhenHidden each time the tab is hidden or shown again. That is the visibilitychange event.
2. Lines 2 and 3: if the tab is hidden and a frame is waiting, cancel that frame.
3. Lines 4 and 5 clear the request id and the last timestamp.
4. Lines 6 and 7: if the tab is shown again and no frame is waiting, ask for a new one.

Why clear previous on line 5? If you don't, the first frame after the tab comes back counts the whole hidden time as elapsed time, and the dot jumps far ahead. Browsers often slow down or stop rAF in hidden tabs anyway, but your own variables still need to be right. When that part of the page is removed, remove the visibilitychange listener too.

The replay below compares the two ways to move the dot. It uses three made-up timestamps: 0, 16.7, and 50 ms. The last frame is late: it comes 33.3 ms after the one before, not about 16.7 ms.

1const timestamps = [0, 16.7, 50];Run2let position = 0;3let previous = timestamps[0];4for (const timestamp of timestamps.slice(1)) {5  const elapsed = timestamp - previous;6  position += 0.12 * elapsed;7  console.log(position.toFixed(2));8  previous = timestamp;9}

Press Step to go line by line. Then switch the setting and replay. Moving by elapsed time prints 2.00 and 6.00. Moving a fixed 2 pixels per frame prints 2.00 and 4.00.

Moving at one speed the whole time often looks stiff. A drawer that starts slowly and stops slowly looks natural. A shake that warns about an error should start fast.

A timing function, also called an easing, controls this. It takes how much of the time has passed, from 0 to 1. It gives back how far along the motion is, usually also from 0 to 1.

CSS has names for common timing functions: linear, ease, ease-in, ease-out, and ease-in-out. Each one is a cubic Bézier curve: a smooth curve set by four numbers, written cubic-bezier(x1, y1, x2, y2). The x numbers are about time. The y numbers are about progress.

The lab below shows this code. cubicBezier is a helper this lesson provides. Line 1 makes an easing function from the four numbers of ease. Lines 2 to 4 print 0, 0.802, and 1. So with ease, half the time gives about 80% of the motion: it moves fast at first and slows near the end.

1const easing = cubicBezier(0.25, 0.1, 0.25, 1);2console.log(easing(0));3console.log(easing(0.5).toFixed(3));4console.log(easing(1));

Two rules for the four numbers:

• The x numbers must stay from 0 to 1. They are about time, and time can't go backward or past the end.
• The y numbers can go below 0 or above 1. Then the motion goes past the end and comes back, like a bounce. This is called overshoot.

CSS can animate too, and it is often simpler and smoother. Use it when you know the motion ahead of time. CSS has two tools for this:

• A transition animates a change from one style to another, like a button that grows a little when the mouse is over it.
• A @keyframes animation plays a list of steps you wrote ahead of time, like a spinner that turns again and again.

With CSS, the browser works out every in-between step for you. For transform and opacity, it can often do this on the compositor: a separate part of the browser that moves and fades parts of the page that are already drawn. It does not need your JavaScript for that.

Your JavaScript runs on the main thread: the one line of work where the browser also handles clicks and works out the page layout. Use JavaScript for motion that needs decisions while it runs:

• live measurements, like how fast the page is scrolling
• physics, like a ball that bounces
• drawing on a canvas
• keyframes that your code builds
• buttons to pause, reverse, or finish the motion

The table compares the four tools. Read each row as: "use this tool for these jobs; this is what it does well; this is what to watch for."

CSS can also tell your JavaScript when an animation ends:

• transitionend fires when the transition of one property ends.
• animationend fires when a CSS @keyframes animation ends.
• If a transition is stopped early, transitionend does not fire.

const button = document.querySelector("button");
const spinner = document.querySelector(".spinner");

button.addEventListener("transitionend", (event) => {
  console.log(event.propertyName);
});
spinner.addEventListener("animationend", () => {
  spinner.classList.remove("is-spinning");
});

Line by line:

1. Lines 1 and 2 find the button and the spinner on the page.
2. Lines 4 to 6: when one of the button's transitions ends, print the name of that property, like transform.
3. Lines 7 to 9: when the spinner's animation ends, remove its is-spinning class.

When that part of the page is removed, remove these listeners too.

<button type="button" id="stop-spinner">Stop loading</button>
<span class="spinner is-spinning" role="status" aria-label="Loading"></span>

<script>
document.querySelector("#stop-spinner").addEventListener("click", () => {
  document.querySelector(".spinner").classList.remove("is-spinning");
});
</script>

<style>
.spinner { display: inline-block; inline-size: 1rem; block-size: 1rem; border: 2px solid currentColor; border-inline-end-color: transparent; border-radius: 50%; }
.spinner.is-spinning { animation: spin 700ms linear infinite; }
@keyframes spin { to { transform: rotate(1turn); } }
@media (prefers-reduced-motion: reduce) { .spinner.is-spinning { animation-duration: 1ms; animation-iteration-count: 1; } }
</style>

Here CSS does the turning. prefers-reduced-motion: reduce on line 14 matches when the person has turned on a "reduce motion" setting on their device. Line by line:

1. Lines 1 and 2 make a Stop button and a spinner with the is-spinning class.
2. Lines 5 to 7: a click on the button removes the is-spinning class.
3. Line 12: while the spinner has that class, it turns once every 700 ms, forever.
4. Line 13 is the @keyframes list: turn all the way around.
5. Line 14: for people who ask for less motion, the spinner turns once, very fast, and stops.

To stop the spinner, you remove a class. There is no JavaScript loop to cancel.

The Web Animations API sits between CSS and your own rAF loop. You call element.animate(keyframes, timing):

• keyframes is a list of styles to move through, like from translateX(0) to translateX(160px).
• timing is an object with options, like duration in milliseconds and easing.

The browser plays the animation for you, so you don't write a frame loop. It also returns an Animation object right away. You use that object to control the animation from your code:

• Methods: play(), pause(), reverse(), and finish().
• Properties: playbackRate is the speed. playState says what it is doing, like "running" or "paused". currentTime is how far in it is, in milliseconds.
• A finished promise. A promise is an object that tells you later when something is done. This one is done when the animation ends.

1const animation = card.animate(2  [3    { transform: "translateX(0)", opacity: 0.6 },4    { transform: "translateX(160px)", opacity: 1 },5  ],6  {7    duration: 900,8    easing: "ease-out",9    iterations: 1,10    direction: "normal",11    fill: "forwards",12  },13);14 15animation.finished.then(() => {16  animation.commitStyles();17  animation.cancel();18});

1const animation = card.animate(2  [3    { transform: "translateX(0)", opacity: 0.6 },4    { transform: "translateX(160px)", opacity: 1 },5  ],6  {7    duration: 900,8    easing: "ease-out",9    iterations: 1,10    direction: "normal",11    fill: "forwards",12  },13);14 15animation.finished.then(() => {16  animation.commitStyles();17  animation.cancel();18});

Line by line:

1. Line 1 calls card.animate() and keeps the Animation object in animation.
2. Lines 3 and 4 are the keyframes: start at translateX(0) with opacity 0.6, and end 160 pixels to the right with opacity 1.
3. Lines 7 to 10 are the timing: 900 ms, ease-out, played once, in the normal direction.
4. Line 11, fill: "forwards", keeps the end style showing after the animation ends. Without it, the card would jump back to where it started.
5. Line 15 waits for the finished promise.
6. Line 16, commitStyles(), writes the end style into the card's own style attribute.
7. Line 17, cancel(), removes the animation. The card stays where it ended, because line 16 saved that style.

Where you'll use this

In real work, pick the simplest tool that does the job:

• A menu that fades in can be a CSS transition, as in the Styles and classes lesson.
• A tutorial card that must pause when a dialog opens can use element.animate().
• A canvas game, or a chart you drag through, can use rAF. Keep slow work, like measuring the page layout, out of the frame function.

const reduceMotion = matchMedia("(prefers-reduced-motion: reduce)").matches;
const duration = fadeDuration(reduceMotion);
const fade = panel.animate(
  [{ opacity: 0 }, { opacity: 1 }],
  { duration, fill: "forwards" },
);
console.log(reduceMotion ? "instant fade" : "400 ms fade");

Line by line:

1. Line 1 asks the browser whether the person wants less motion. matchMedia() checks a CSS media query, and .matches is true or false.
2. Line 2 uses fadeDuration, a helper this lesson provides: 1 ms for less motion, 400 ms otherwise.
3. Lines 3 to 6 fade the panel from opacity 0 to 1 and keep the end style.
4. Line 7 prints which fade was used.

The panel still appears, so the person still sees that something changed. It just doesn't take a long trip across the screen.

Only the browser knows this setting. The server builds the page before it reaches the browser, so it can't read it. Run code like this in the browser, after the page loads, for example in a click handler.

• "rAF means 60 frames a second." It means "just before the next repaint." A screen might draw 60, 90, or 120 frames a second, a number that changes, or fewer in a hidden tab.
• "Moving 2 pixels per frame is fine." Then the speed changes from screen to screen, and the motion falls behind after a slow frame.
• "All CSS animation is free." Animating transform and opacity is often cheap. Animating sizes or positions, like width or top, makes the browser work out the layout again on every frame, and that can be slow.
• "JavaScript animation runs off the main thread." Normal rAF callbacks, and style changes made from JavaScript, run on the main thread with the rest of your code.
• "fill: "forwards" cleans up." It keeps the end style showing. It does not remove the finished animation. commitStyles() and then cancel() do that.
• "Reduced motion means no animation design." It means less movement: instant changes, short fades, or progress in small steps.

Key takeaways

• requestAnimationFrame runs your code just before the next repaint. It passes a timestamp that every rAF callback in that frame shares.
• Moving by elapsed time keeps the speed right after slow frames and on fast screens. Moving a fixed amount per frame does not.
• A timing function shapes the speed. In cubic-bezier(), the x numbers stay from 0 to 1; the y numbers can go past that.
• Use CSS for motion you know ahead of time, element.animate() for motion your code builds or controls, and rAF when every frame needs new math.
• Respect reduced motion, don't start motion on your own, animate transform and opacity, and clean up loops and finished animations.

JavaScript animation changes what you see one frame at a time: ask the browser for each frame, measure the real time, and pick the simplest tool that gives you the control you need.

Up next: Drawing with canvas.