# requestAnimationFrame & VSync

- **Canonical URL:** https://frontend.rocks/concepts/requestanimationframe-vsync/
- **Domain:** Rendering Pipeline
- **Baseline / Maturity Status:** Baseline · Widely
- **Last Verified:** 2026-11-15
- **TL;DR:** requestAnimationFrame schedules callbacks right before the browser paints the next VSync frame, matching display refresh rates.

## Prerequisites
- [Event Loop, Macrotasks, and Microtask Queue](https://frontend.rocks/concepts/event-loop-tasks-microtasks.md): rAF runs in the rendering step of the HTML event loop after tasks and microtasks.
- [Browser Rendering Pipeline (Critical Rendering Path)](https://frontend.rocks/concepts/browser-rendering-pipeline.md): Mutations inside rAF are batched directly into the upcoming Style/Layout/Paint cycle.

## Primary Sources
- https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#animation-frames
- https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame

---
## TL;DR

`requestAnimationFrame` (rAF) aligns JavaScript visual updates with the display's VSync cadence. Callbacks execute once per frame right before Style, Layout, and Paint, eliminating wasted intermediate renders and automatically pausing in background tabs.

## Interactive Lab

Trace how VSync triggers rAF execution and frame commit inside `StepMachineLab`.

## Under the Hood

Using `setInterval(fn, 16)` for animation is like mailing letters without checking when the postal truck leaves, some frames get two deliveries, others get zero. `requestAnimationFrame` hands your update directly to the driver as the truck pulls out.

1. **VSync Alignment**: The compositor signals `BeginMainFrame` in sync with the monitor's refresh rate (60Hz, 120Hz, or 144Hz).
2. **Queue Snapshotting**: The [Event Loop](/concepts/event-loop-tasks-microtasks) drains tasks, then runs every queued rAF callback for the current frame. Calls to `requestAnimationFrame` made inside a callback defer to the next VSync.
3. **Single Render Pass**: All DOM mutations inside rAF coalesce into one pass of the [Browser Rendering Pipeline](/concepts/browser-rendering-pipeline).

```js
let last = 0;
function tick(timestamp) {
  const dt = last ? (timestamp - last) / 1000 : 0;
  last = timestamp;
  box.style.transform = `translateX(${(timestamp * 0.08) % 300}px)`;
  if (dt < 1) requestAnimationFrame(tick);
}
requestAnimationFrame(tick);
```

## Problem Genealogy

- **2000–2010**: `setTimeout(fn, 16)` drifted out of phase with display refreshes, causing frame tearing and battery drain in hidden tabs.
- **2011+**: Browser vendors standardized `requestAnimationFrame`, throttling background tabs to 0–1Hz and syncing foreground tabs to VSync.

## Production Pitfalls

- **Frame-rate-dependent speed**: Incrementing `x += 2` per rAF callback runs twice as fast on a 120Hz screen as on a 60Hz screen; always use `timestamp` deltas.
- **Multiple rAF loops**: Spawning independent rAF loops per component fragments main-thread timing and invites [Layout Thrashing](/concepts/layout-thrashing).
- **When not to use `requestAnimationFrame`**: Do not use rAF for simple `transform` or `opacity` transitions; use CSS transitions, the Web Animations API, or [Scroll-Driven Animations](/concepts/scroll-driven-animations) so they run off the main thread.
