Web animation: GSAP, Lenis & Three.js

01How the browser draws a frame

To animate well you need to know what the browser does 60 or more times per second. For each frame it may run JavaScript, recalculate styles, do layout (work out sizes and positions), paint (fill pixels) and composite (stack layers on the GPU). Changing width, height, top or margin forces layout and paint, which is expensive. Changing transform and opacity can usually skip both and happen only in the compositor, which is cheap. That is why smooth animations move things with translate, scale and rotate, and fade with opacity. You have about 16 milliseconds per frame at 60Hz, and less on 120Hz screens, so every unnecessary layout costs you.

• Cheap: transform (translate, scale, rotate), opacity, filter in many cases.
• Expensive: width, height, top, left, margin, padding, box-shadow size.
• Layout thrash: reading layout (offsetHeight) right after writing styles, in a loop.

02GSAP basics and timelines

GSAP animates any numeric property over time. A tween is one animation: gsap.to() animates to values, gsap.from() animates from values to the current state, and gsap.fromTo() sets both ends. A timeline is a sequence of tweens with precise control over overlaps, using the position parameter: '<' starts with the previous tween, '-=0.2' overlaps by 0.2 seconds. Timelines can be paused, reversed, sped up and scrubbed, which makes them perfect for intros and scroll stories. Since 2025 GSAP and all its plugins, including SplitText and ScrollTrigger, are free for commercial use. In React, use the useGSAP hook from @gsap/react: it scopes selectors to a container and reverts every animation on unmount.

1"use client";
2import { useRef } from "react";
3import gsap from "gsap";
4import { useGSAP } from "@gsap/react";
5 
6gsap.registerPlugin(useGSAP);
7 
8export function Intro() {
9  const root = useRef<HTMLDivElement>(null);
10  useGSAP(() => {
11    const tl = gsap.timeline({ defaults: { ease: "power3.out", duration: 0.8 } });
12    tl.from(".title", { y: 40, autoAlpha: 0 })
13      .from(".lead", { y: 20, autoAlpha: 0 }, "-=0.5")
14      .from(".cta", { scale: 0.9, autoAlpha: 0 }, "<0.2");
15  }, { scope: root });
16  return <div ref={root}>{/* .title .lead .cta */}</div>;
17}

03ScrollTrigger and SplitText

ScrollTrigger connects an animation to the scroll position. You set a trigger element and start and end points such as 'top 80%' (when the element's top reaches 80% down the viewport). With scrub: true the animation follows the scrollbar; with pin: true the element stays fixed while the timeline plays. Use markers: true while developing. SplitText splits text into lines, words or characters so you can stagger them. The 2025 rewrite is smaller, re-splits on resize with autoSplit, can wrap lines in masks for reveal effects, and adds an aria-label to the parent while hiding the split pieces from screen readers. Always wait for fonts to load before splitting, or line breaks will be wrong.

1gsap.registerPlugin(ScrollTrigger, SplitText);
2 
3document.fonts.ready.then(() => {
4  SplitText.create(".headline", {
5    type: "lines",
6    mask: "lines",
7    autoSplit: true,
8    onSplit: (self) =>
9      gsap.from(self.lines, {
10        yPercent: 100,
11        stagger: 0.08,
12        scrollTrigger: { trigger: ".headline", start: "top 80%" },
13      }),
14  });
15});

04Smooth scrolling with Lenis

Lenis is a small library that smooths wheel and trackpad scrolling while keeping native scroll behaviour: the page still scrolls the document, so position: sticky, anchors and accessibility tools keep working. The key integration point is ScrollTrigger: both must use the same clock and the same scroll position. You drive Lenis from GSAP's ticker and tell ScrollTrigger to update on every Lenis scroll event. Turn off GSAP's lag smoothing so they never drift apart. Be careful with nested scroll areas (modals, dropdowns): mark them with data-lenis-prevent so they scroll natively. Respect reduced motion by not starting Lenis at all for those users.

1import Lenis from "lenis";
2import gsap from "gsap";
3import { ScrollTrigger } from "gsap/ScrollTrigger";
4 
5gsap.registerPlugin(ScrollTrigger);
6 
7const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
8if (!reduce) {
9  const lenis = new Lenis({ lerp: 0.1 });
10  lenis.on("scroll", ScrollTrigger.update);
11  gsap.ticker.add((time) => lenis.raf(time * 1000));
12  gsap.ticker.lagSmoothing(0);
13}

05Three.js basics

Three.js is a library over WebGL (and now WebGPU) for 3D in the browser. Every scene needs four things: a Scene that holds objects, a Camera that looks at it, a Renderer that draws to a canvas, and Meshes, which are a geometry (the shape) plus a material (how it looks). Lights are needed for most materials. An animation loop updates objects and renders each frame. For performance, cap the pixel ratio at 2, reuse geometries and materials, pause rendering when the canvas is off-screen, and call dispose() on geometries, materials and textures when a component unmounts, otherwise GPU memory leaks. In React projects, React Three Fiber wraps the same ideas in components.

1import * as THREE from "three";
2 
3const canvas = document.querySelector("canvas")!;
4const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true });
5renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
6renderer.setSize(canvas.clientWidth, canvas.clientHeight, false);
7 
8const scene = new THREE.Scene();
9const camera = new THREE.PerspectiveCamera(45, canvas.clientWidth / canvas.clientHeight, 0.1, 100);
10camera.position.z = 4;
11 
12const mesh = new THREE.Mesh(new THREE.IcosahedronGeometry(1, 1), new THREE.MeshNormalMaterial());
13scene.add(mesh);
14 
15renderer.setAnimationLoop((t) => {
16  mesh.rotation.y = t * 0.0004;
17  renderer.render(scene, camera);
18});

06Performance: transform, will-change and layout thrash

Most janky animations come from three causes. First, animating layout properties; switch to transforms (GSAP's x, y, scale and rotation already use transform). Second, layout thrash: code that writes a style, then reads offsetHeight or getBoundingClientRect, then writes again, forcing the browser to recalculate layout repeatedly inside one frame. Batch all reads first, then all writes. Third, too many layers or a huge painted area. will-change: transform promotes an element to its own GPU layer, which helps for an element that is about to animate, but every layer costs memory, so add it shortly before and remove it after, never on hundreds of elements. Profile in the Chrome DevTools Performance panel: long purple (layout) and green (paint) blocks show the problem.

• Animate x, y, scale, rotation and autoAlpha in GSAP.
• Read all measurements first, then write styles.
• Use will-change sparingly and temporarily.
• Kill ScrollTriggers and tweens on route change to avoid leaks.

07Reduced motion and accessibility

Some people get dizzy or nauseous from large movement, parallax and zooming. They turn on 'reduce motion' in their operating system, and the browser exposes it as the prefers-reduced-motion media query. Respect it: keep fades and colour changes, but drop big movements, parallax, auto-playing loops and smooth-scroll hijacking. gsap.matchMedia() lets you define animations per condition and reverts them automatically when the condition changes. Equally important: the page must be complete without JavaScript. Content hidden in CSS waiting for an animation to reveal it should have a visible end state if the script fails. Never animate focus away, keep anything that moves for more than five seconds pausable (a WCAG requirement), and avoid flashing more than three times per second.

1const mm = gsap.matchMedia();
2 
3mm.add("(prefers-reduced-motion: no-preference)", () => {
4  gsap.from(".card", { y: 60, autoAlpha: 0, stagger: 0.1,
5    scrollTrigger: { trigger: ".cards", start: "top 75%" } });
6});
7 
8mm.add("(prefers-reduced-motion: reduce)", () => {
9  gsap.from(".card", { autoAlpha: 0, duration: 0.3 });
10});

08Compositor layers: what the GPU really does

When you animate transform or opacity, the browser can move an element on the compositor thread, separate from the main thread where JavaScript runs. For that the element needs its own layer: a bitmap stored in GPU memory. Browsers promote elements automatically during CSS transitions and Web Animations API transforms, or when you set will-change: transform. Each layer costs roughly width times height times four bytes, multiplied by the device pixel ratio squared, so one full-screen layer on a 3x phone is already more than ten megabytes. Promote a few hundred cards and mobile browsers start dropping frames or even reload the tab. Note the important difference: CSS and Web Animations API animations of transform can keep running even while the main thread is blocked, but JavaScript-driven animations, including GSAP, calculate every frame on the main thread, so long tasks make them stutter. Inspect what is promoted with the DevTools Layers panel and the Rendering tab's layer borders.

• Layer memory scales with area and pixel ratio squared, not with element count alone.
• Overlapping a promoted layer can force other elements into layers too (layer explosion).
• For effects that must survive a busy main thread, prefer CSS or the Web Animations API.

09High-frequency motion: quickTo, overwrite and the ticker

Some motion updates dozens of times per second: a cursor follower, a magnetic button, parallax reacting to the pointer. Creating a new gsap.to() on every pointermove allocates objects and produces tweens that fight each other. gsap.quickTo() builds one reusable function per property that simply retargets a single tween, which is far cheaper. When several tweens may animate the same property, set overwrite: 'auto' so GSAP kills only the overlapping part of the older tweens. All GSAP animation runs on one ticker built on requestAnimationFrame; hook your own per-frame logic into gsap.ticker.add() instead of starting a second loop, so everything stays in sync and pauses together. GSAP also applies lag smoothing after a long frame so motion does not jump. Inside these handlers, never read layout; cache element sizes on resize with a ResizeObserver and only write transforms.

1import gsap from "gsap";
2 
3const xTo = gsap.quickTo(".cursor", "x", { duration: 0.4, ease: "power3" });
4const yTo = gsap.quickTo(".cursor", "y", { duration: 0.4, ease: "power3" });
5 
6window.addEventListener(
7  "pointermove",
8  (e) => {
9    xTo(e.clientX);
10    yTo(e.clientY);
11  },
12  { passive: true },
13);
14 
15// one shared per-frame hook instead of a separate requestAnimationFrame loop
16gsap.ticker.add((time, deltaTime) => {
17  /* update custom state with deltaTime (ms) */
18});

10ScrollTrigger edge cases that break in production

ScrollTrigger calculates start and end positions and caches them, so anything that changes the page height later makes triggers fire in the wrong place: images without dimensions, web fonts swapping in, client-fetched content, accordions opening. Reserve space for media and call ScrollTrigger.refresh() after such changes; it already runs on load and resize. Create triggers in the order they appear on the page, or set refreshPriority, because pinning a section adds spacing that shifts everything below it. On phones, the address bar showing and hiding resizes the viewport; ScrollTrigger.config({ ignoreMobileResize: true }) skips refreshes for those vertical resizes, and heights in svh units stay stable. Pinning inside a transformed parent misbehaves, because position: fixed becomes relative to any ancestor with a transform; pin the outer section instead. In single-page navigation, kill old triggers before new ones are created, or positions from the previous page leak into the next.

1gsap.registerPlugin(ScrollTrigger);
2 
3ScrollTrigger.config({ ignoreMobileResize: true });
4 
5// recalc once fonts and late content are in place
6document.fonts.ready.then(() => ScrollTrigger.refresh());
7 
8new ResizeObserver(() => ScrollTrigger.refresh()).observe(
9  document.querySelector("main")!,
10);

11Three.js at scale: draw calls, shaders and WebGPU

A 3D scene is usually limited by draw calls and shader work, not by triangle count. Each mesh with its own material is at least one draw call, so a thousand identical objects as separate meshes cost a thousand calls; one InstancedMesh draws them all in a single call with a matrix per instance. Merge static geometry and share materials so the GPU switches state less often. The first frame that uses a new material compiles its shader on the main thread, which can freeze the page for hundreds of milliseconds; precompile with renderer.compileAsync() before revealing the scene. For scenes that change only on interaction, render on demand instead of every frame (in React Three Fiber, frameloop='demand'). Watch renderer.info for live draw calls, triangles, geometries and textures; growing numbers across navigations mean a leak. Three.js also ships a WebGPURenderer that falls back to WebGL 2 and enables compute shaders, but plain WebGL remains the safest choice when broad device support matters.

1import * as THREE from "three";
2 
3const count = 2000;
4const mesh = new THREE.InstancedMesh(
5  new THREE.SphereGeometry(0.05, 12, 12),
6  new THREE.MeshStandardMaterial({ color: 0xdddddd }),
7  count,
8);
9const m = new THREE.Matrix4();
10for (let i = 0; i < count; i++) {
11  m.setPosition(Math.random() * 10 - 5, Math.random() * 10 - 5, Math.random() * -10);
12  mesh.setMatrixAt(i, m);
13}
14scene.add(mesh); // 2,000 spheres, one draw call
15 
16await renderer.compileAsync(scene, camera); // avoid first-frame shader jank
17console.log(renderer.info.render.calls);