Scrollcraft
Chapter 8 of 15RO

WebGL: a scene behind the page.

three.js draws with the graphics card, which is how agency sites get depth, light and particles that CSS cannot. Four scenes below, each tied to the scroll and running live beside its code.

Chapter 8 of 154 min read

What you will learn

By the end of this chapter
  1. 01Set up a three.js scene with a renderer, a camera, lights and one object.
  2. 02Drive a scene from the scroll position, drawing only when something changes.
  3. 03Move work to the graphics card with shaders and buffer attributes.
  4. 04Keep WebGL fast and safe: a pixel ratio cap, cleanup, reduced motion and a fallback.

01 · Before you start

When WebGL is worth it
a

Use it for one hero moment

A product you can turn, a field of light, a transition between two images. One scene that carries the story is worth the weight; a scene in every section is not.

b

Load it as a module

three.js ships as an ES module. On a plain page, an import map tells the browser where three lives; with a bundler, install it from npm and import it the same way.

bash
npm install three
c

Always have a fallback

Some machines have no WebGL: old hardware, remote desktops, locked-down lab computers. Create the renderer inside try and keep the page readable without it.

JavaScript
const canvas = document.querySelector('canvas.gl');
let renderer;
try {
  renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
} catch {
  // no WebGL: say so, and keep the page readable without the scene
  document.documentElement.classList.add('no-webgl');
}

02 · Four scenes, live

Scroll inside each preview
1

A scene driven by scroll

A mesh, two lights and a camera. The scroll position turns the object and moves the camera in, and the scene is drawn only when the scroll changes.

Rendering on scroll instead of in a constant loop leaves the graphics card idle while the reader is reading.

HTML
<script type="importmap">
  { "imports": { "three": "https://cdn.jsdelivr.net/npm/three@0.187.0/build/three.module.js" } }
</script>
<canvas class="gl" aria-hidden="true"></canvas>
<p class="nogl">This device has no WebGL. The page still reads in full.</p>
<main>
  <section><h2>A scene behind the page</h2></section>
  <section><h2>Scroll turns it</h2></section>
  <section><h2>and moves the camera in</h2></section>
</main>
2

Particles moved on the GPU

Twelve thousand points, each with two positions. A small vertex shader mixes them by one number, so the move costs JavaScript nothing however many points there are.

Anything you would update per point in a loop belongs in a shader attribute and a uniform.

HTML
<script type="importmap">
  { "imports": { "three": "https://cdn.jsdelivr.net/npm/three@0.187.0/build/three.module.js" } }
</script>
<canvas class="gl" aria-hidden="true"></canvas>
<p class="nogl">This device has no WebGL. The page still reads in full.</p>
<main>
  <section><h2>Twelve thousand points</h2></section>
  <section><h2>leave a sphere</h2></section>
  <section><h2>and settle into a wave.</h2></section>
</main>
3

A full-screen shader

One rectangle covering the screen and a fragment shader that paints every pixel. Noise drifts with time; the scroll shifts the light from night to dawn.

A soft backdrop can render at 1x pixel ratio. Nobody sees the difference, and it costs a quarter of the work on a retina screen.

HTML
<script type="importmap">
  { "imports": { "three": "https://cdn.jsdelivr.net/npm/three@0.187.0/build/three.module.js" } }
</script>
<canvas class="gl" aria-hidden="true"></canvas>
<p class="nogl">This device has no WebGL. The page still reads in full.</p>
<main>
  <section><h2>One shader, full screen</h2></section>
  <section><h2>Time moves it slowly.</h2></section>
  <section><h2>Scroll changes the light.</h2></section>
</main>
4

A cinematic transition

Two images on one rectangle, and a shader that switches from one to the other along a ragged edge as you scroll, while both slide a little: a dissolve that reads as a camera move.

The preview draws its two images in code. With photographs, load them with TextureLoader and set colorSpace to sRGB.

HTML
<script type="importmap">
  { "imports": { "three": "https://cdn.jsdelivr.net/npm/three@0.187.0/build/three.module.js" } }
</script>
<canvas class="gl" aria-hidden="true"></canvas>
<p class="nogl">This device has no WebGL. The page still reads in full.</p>
<main>
  <section><h2>From one scene</h2></section>
  <section><h2>to the next,</h2></section>
  <section><h2>with a dissolve driven by scroll.</h2></section>
</main>

03 · Keep it fast

The budget
a

Cap the pixel ratio and render on demand

Two settings decide most of the cost: how many pixels you draw and how often. Clean up what you create when the scene goes away, or a single-page site leaks memory with every visit.

JavaScript
renderer.setPixelRatio(Math.min(devicePixelRatio, 2)); // past 2x the cost grows, the gain does not

// draw only when something changed
addEventListener('scroll', () => requestAnimationFrame(render), { passive: true });

// when the scene leaves the page for good, give the memory back
geometry.dispose();
material.dispose();
texture.dispose();
renderer.dispose();
b

Respect reduced motion

Every preview reads prefers-reduced-motion: the scenes hold still, the particles show their final shape, the shader stops drifting and the transition cuts instead of dissolving.

c

Check it on a real phone

Desktop graphics cards hide problems. Open the page on a mid-range phone, scroll it for a minute, and feel whether it gets warm. If it does, lower the pixel ratio or the point count first.

Practice · Work with AI

The same task in your tool

WebGL prompts need limits more than any other: the AI will happily add post-processing and shadows a phone cannot afford.

Open a terminal in the project folder and run claude. Press Shift+Tab until plan mode is on, paste the prompt, read the plan, then approve it. Project rules go in CLAUDE.md.

A hero scene

Prompt
Read CLAUDE.md. Add a three.js 0.187.0 scene behind the hero of the site for [subject], loaded as an ES module through an import map from jsDelivr. One object, two lights, no shadows, no post-processing. The scroll position rotates the object and moves the camera; draw only when the scroll changes. Cap the pixel ratio at 2, create the renderer inside try and show a still image when WebGL is missing, and keep the scene still under prefers-reduced-motion.

Performance pass

Prompt
Measure the hero scene: frame time while scrolling, draw calls, and texture memory. Tell me the single change that would help a mid-range phone most. Do not change anything yet.

Practice · Exercises

Try first, then compare
1

Render on demand

The scene draws 60 times a second even when the page is still. Change it to draw only when the scroll changes.

Hint: request one frame from the scroll listener.

Show the solution

Remove the continuous loop and queue a single frame when the scroll moves, so the graphics card rests while the reader reads.

JavaScript
let queued = false;
function render() {
  queued = false;
  mesh.rotation.y = scrollY * 0.002;
  renderer.render(scene, camera);
}
addEventListener('scroll', () => {
  if (!queued) { queued = true; requestAnimationFrame(render); }
}, { passive: true });
render();
2

The fallback

Make the page readable on a computer without WebGL.

Hint: the renderer constructor throws when WebGL is unavailable.

Show the solution

Create the renderer inside try; in catch, add a class to the html element that hides the canvas and shows a still image or nothing at all. The text must never depend on the scene.

3

Where the cost goes

A particle hero is smooth on a laptop and stutters on a phone. List three changes, cheapest first.

Hint: pixels, then points, then effects.

Show the solution

1. Cap the pixel ratio lower (1.5 or 1). 2. Use fewer points on small screens. 3. Remove extra passes such as bloom. Measure after each change.

Practice · Course project

One site, built across the course

If a 3D moment serves the story of [subject], add one. If it does not, skip this step: restraint is a design decision too.

  1. Decide whether the hero gains anything from depth. Write the reason in notes.md.
  2. If yes, run “A hero scene”, then “Performance pass”.
  3. Turn off WebGL in the browser (or test on an old device) and check the fallback.
  4. Commit, with the three.js version pinned in the import map.

Practice · Test it

Check the result
  • The scene draws only while you scroll: the Performance panel is quiet when the page is still.
  • With WebGL disabled, the page reads in full with no errors.
  • With reduced motion on, the scene does not move.
  • On a real phone, scrolling past the hero does not stutter or heat the device.

Practice · Assessment

Acceptance criteria

0 of 4 criteria met

Next Examples

Five portfolio projects: a product launch, a studio portfolio, a long-read, an agency case study in GSAP and a product in WebGL. Each runs live, responsive and calm under reduced motion, with a brief, prompts and full code.

Keyboard shortcuts: [ previous chapter · ] next chapter