Web Animation Perf

Web Animation Performance

Guidance for writing smooth, GPU-accelerated animations on the web. Most jank comes from three avoidable mistakes; the rest is diagnostic technique.

The Three Cardinal Rules

1. Never combine transition: all <duration> with JS that updates the same property every frame

This is the single most common animation bug. If JS updates left/top/transform on every tick AND the element has transition-all duration-700 (or similar), CSS will linearly interpolate between every pair of successive JS values over the transition duration. For non-linear motion (orbit, arc, easing curve) the linear chord cuts across the intended path — e.g., rotating nodes appear to drift inward toward the center, parallax elements ghost-trail, scroll-linked effects lag noticeably behind the scroll.

Pick exactly one driver:

• Pure CSS: @keyframes + animation: spin 8s linear infinite and let the browser handle it.
• Pure JS: set the final position every frame; no transition on that property. Use a separate, narrower transition only for state changes (e.g., active/inactive scale and color).

If you want a transition on hover/active states but JS-driven continuous motion on position, scope the transition to the specific properties (transition: transform 300ms, background-color 300ms) and exclude the JS-driven property.

2. Use requestAnimationFrame, never setInterval, for continuous motion

Always integrate by elapsed time, not by fixed step-per-tick. Motion stays correct under dropped frames:

useEffect(() => {
  let lastFrame = performance.now();
  let id = 0;
  const tick = (now) => {
    const dt = Math.min(now - lastFrame, 100); // clamp to handle tab-switch gaps
    lastFrame = now;
    const degrees = SPEED_DEG_PER_SEC * (dt / 1000);
    setRotation((prev) => (prev + degrees) % 360);
    id = requestAnimationFrame(tick);
  };
  id = requestAnimationFrame(tick);
  return () => cancelAnimationFrame(id);
}, []);

3. Animate transform and opacity. Avoid left/top/width/height/margin/padding

Only transform and opacity skip layout & paint and run entirely on the GPU compositor. Anything else triggers reflow on every change — fine once on hover, catastrophic at 60Hz.

For static positioning (rendered once and not animated), left/top is fine. The rule applies to continuously animated properties.

Supporting practices

Promote to a compositor layer with will-change

style={{ willChange: 'transform, opacity' }}

Only on elements that actually animate continuously. Overusing will-change consumes GPU memory.

Drive DOM directly via refs when state-driven re-renders dominate

If profiling shows React reconciliation is the bottleneck (rare for <50 elements), bypass React for the per-frame update:

const nodeRefs = useRef([]);
// in rAF tick:
nodeRefs.current[idx].style.transform = `translate3d(${x}px, ${y}px, 0)`;

Re-render via React state only when a meaningful semantic change occurs (e.g., the highlighted node changes), not for every frame.

When in doubt about animation-state correctness, sample DOM positions

Use Playwright or DevTools to actually measure rendered geometry. For circular motion you can verify positions land on the orbit ring:

// In Playwright page.evaluate, sample every 200ms for ~1s
const nodes = Array.from(document.querySelectorAll('.orbital-node'));
const ratios = nodes.map((n) => {
  const r = n.getBoundingClientRect();
  const dx = r.left + r.width / 2 - centerX;
  const dy = r.top + r.height / 2 - centerY;
  return Math.hypot(dx, dy) / expectedOrbitRadius; // should be 1.00
});

If ratios drift below 1.00 (toward center), rule 1 is broken: a CSS transition is fighting JS updates. If ratios are correct but the animation looks janky, suspect rule 2 (timer/rAF) or rule 3 (left/top reflow).

Canvas? Almost never the right answer for UI

For ≤ ~100 DOM elements, GPU-composited transform animation is faster than canvas redraw and keeps accessibility, click targets, hover states, and inspectability for free. Reach for canvas only when (a) element count is in the thousands, (b) you need pixel-level rendering control (particles, fluid sim), or (c) the layout doesn't map to a DOM tree.