Skip to content

A WebGL loading screen before JavaScript

How I build the loading screen for heavy WebGL demos: in the static HTML, CSS-only motion, a 1.6 s floor, a 10 s cap, and an exit on the first real frame.

· 4 min read

The Rune Cast loading screen, a ring of 24 runes lighting up around a progress counter on a dark night sky

A loading screen for a WebGL page only helps if it is there before the JavaScript arrives. On this site the loader is part of the static HTML, it animates with CSS alone, it stays for at least 1.6 seconds and at most 10, and it leaves only when the scene has drawn its first finished frame.

Every example in the Lab, from the Rune Cast stone circle to the ad previews, goes through the same component. The look changes per example; the timing and the rules do not.

Why it has to be in the HTML#

The engine chunk for a 3D example is the heaviest thing on the page. If the loader is rendered by the same JavaScript that loads the engine, the visitor first sees nothing, then a loader, then the scene. On a slow phone that blank moment looks like a broken page.

This is a static Next.js export, so a client component still renders to HTML at build time. The loader is part of that HTML, which means it is painted with the first frame, before React hydrates and long before Three.js is downloaded. Its animation is CSS keyframes on transform and opacity, so it moves while the main thread is busy parsing the engine.

Two details make that safe:

  • A <noscript> style hides the panel, so a visitor without JavaScript sees the HTML poster and the text instead of a loader that never ends.
  • The panel is opaque. A see-through loader shows the poster, the half-built canvas and the loader at once, which looks broken.

That second point bit me once. The Lumora sign-in skin used a multi-layer Tailwind arbitrary value for its background, Tailwind never generated the class, and the panel shipped transparent. Nothing failed in the build. The fix was plain CSS in the skin's own stylesheet, and I now look at loader frames in screenshots, not only at the finished scene.

The counter has to keep moving#

A percentage that stops at 90 reads as a hang. The engine does not report real progress for shader compilation or GPU uploads, so the counter is a curve over time, not a measurement:

// About 75 at 3 s, 87 at 7 s, 92 at 10 s; it never reaches 100 on its own.
const idleProgress = (ms: number) =>
  60 * (1 - Math.exp(-ms / 700)) + 38 * (1 - Math.exp(-ms / 5500));

The first term runs quickly to about 60. The second is a long tail that keeps ticking, so even a slow phone sees the number change every second. When the scene is ready, the counter eases from wherever it is to 100 in 450 ms.

A floor of 1.6 seconds#

On a fast machine the scene can be ready in 300 ms. A loader that appears and vanishes in that time is a flash, and a flash looks like a bug. So the count to 100 never ends sooner than 1.6 s after the start:

endAt = reducedMotion ? now : Math.max(now + FINISH_MS, start + MIN_MS);

This is a deliberate delay, and it costs time on fast devices. I accept that for the Lab because the loader is part of the piece; I would not put a minimum on a content page.

A cap of 10 seconds#

The opposite failure is a loader that never leaves. If the experiment has not reported ready after 10 seconds, the mount marks it ready anyway. The scene may still be warming up, but the visitor can scroll, read and use the HTML fallback. If WebGL is missing, the poster stays and says so; you can see what a device supports in the WebGL report.

Ready means the first finished frame#

"The chunk loaded" is too early. Between the download and a usable picture come shader compilation, texture decoding and the first render. Each experiment gets an onReady callback and calls it after the first frame that looks like the scene, not after the first requestAnimationFrame. Some experiments also wait for the lab:reveal event the loader fires as it starts to leave, so the entrance animation plays in view and not under the panel.

No jumps while it loads#

A fullscreen loader locks scrolling while it is visible: overflow: hidden on the root, a scroll to the top and Lenis stopped. Without the Lenis stop, smooth scrolling keeps its own position and the page jumps when the panel leaves. I wrote about the Lenis side in Lenis and reduced motion.

The other half is scrollbar-gutter: stable on the root. Hiding overflow removes the scrollbar, and without a reserved gutter the whole layout shifts sideways by its width at the start and again at the end.

The exit is designed too#

The panel slides up over 700 ms (translate: 0 -100%) when it is fullscreen, and fades when it sits inside a frame. Each example has its own skin in CSS and SVG only, with no images and no engine code, so the skin is ready at first paint and adds nothing to the engine chunk. Rune Cast lights its ring of 24 runes as the counter climbs; other skins draw a floor plan, assemble a rack or fill an orbit ring.

Under prefers-reduced-motion all of this collapses: no minimum delay, no counting animation, and the panel is removed as soon as the scene is ready.

What it does not fix#

A loader hides waiting; it does not remove it. The engine still has to stay out of every page that does not need it, which I covered in Keeping Three.js out of your main bundle. The chunk is also requested only when the frame is near the viewport and the browser is idle, so the loader is the last layer, not the first.