Building an interactive WebGL water hero in React — and the four bugs it cost me

Melis Su Kaya — Thu, 20 Aug 2026 20:39:00 +0000

I wanted a hero section that reacts to being touched. Not a video loop of water,
not a looping GIF — an actual surface that ripples where you click it.

The effect itself took an afternoon. Everything around it took considerably
longer, and that is the part worth writing down.

Here is what it ended up looking like: live demo

The simulation

The heavy lifting is done by jquery.ripples,
a small plugin that runs a shallow-water simulation in WebGL. It stores a height
field in a texture and steps it with the classic wave update:

float average = (
  texture2D(texture, coord - dx).r +
  texture2D(texture, coord - dy).r +
  texture2D(texture, coord + dx).r +
  texture2D(texture, coord + dy).r
) * 0.25;

info.g += (average - info.r) * 2.0;   // velocity
info.g *= 0.995;                      // damping
info.r += info.g;                     // height

Then it refracts the background image along the surface normal. That is the
whole trick.

Getting a jQuery plugin into React

The plugin is from an era when everything attached itself to a global jQuery.
That is awkward inside a bundler, but not hard — import it dynamically and set
the global first:

useEffect(() => {
  const node = surfaceRef.current;
  if (!node) return;

  let $el = null;
  let cancelled = false;

  async function initRipples() {
    const { default: $ } = await import("jquery");
    window.jQuery = $;
    window.$ = $;
    await import("jquery.ripples");

    if (cancelled) return;
    $el = $(node);
    $el.ripples({ resolution: 512, dropRadius: 24, perturbance: 0.026 });
  }

  initRipples();

  return () => {
    cancelled = true;
    if ($el) $el.ripples("destroy");
  };
}, []);

Two things matter here. The dynamic import() means jQuery and the plugin end
up in their own chunk instead of blocking first paint. And the cancelled flag
matters because in StrictMode the effect runs twice in development — without it
you can initialise onto an element that is already being torn down.

Turning the interaction off

By default the plugin ripples wherever your mouse moves. It looks great in a
demo GIF and terrible on a real page: the water is in constant motion directly
behind your headline, and the eye never settles enough to read it.

So I switched its pointer tracking off and fire drops manually instead:

$el.ripples({ /* ... */ interactive: false });

const dropAt = (clientX, clientY) => {
  const rect = node.getBoundingClientRect();
  $el.ripples("drop", clientX - rect.left, clientY - rect.top, 32, 0.1);
};

node.addEventListener("mousedown", (e) => dropAt(e.clientX, e.clientY));
node.addEventListener("touchstart", (e) => {
  for (const t of e.changedTouches) dropAt(t.clientX, t.clientY);
}, { passive: true });

Now the surface is still until someone deliberately touches it. Much calmer,
and the interaction feels intentional rather than incidental.

The contrast problem nobody warns you about

Bright water plus white type is a losing combination. The caustics are almost
pure white in places, and thin light type simply disappears into them.

Drop shadows on the text help a little. What actually fixed it was a permanent
veil across the middle of the overlay gradient:

<div className="absolute inset-0 bg-[linear-gradient(to_bottom,
  rgba(20,74,99,0.38) 0%,
  rgba(20,74,99,0.17) 18%,
  rgba(20,74,99,0.18) 44%,   /* <- the bit that matters */
  rgba(20,74,99,0.10) 62%,
  rgba(242,251,254,0.55) 90%,
  rgb(242,251,254) 100%)]" />

A uniform dark overlay would have killed the effect. Concentrating it where the
type sits keeps the water bright at the edges and readable in the middle.

The four bugs

1. `100vh` is not the viewport on mobile Safari

The hero was h-screen, which compiles to height: 100vh. On iOS that resolves
to the large viewport — the one you get when the URL bar is hidden. So the
bottom of the hero sat underneath the URL bar, and jumped whenever the bar
collapsed.

100svh — the small viewport — is always fully visible and never resizes:

.h-hero { height: 100vh; }

@supports (height: 100svh) {
  .h-hero { height: 100svh; }
}

dvh is the tempting one, but it resizes as the bar hides, which reintroduces
the jump. svh is the right choice for a hero.

2. Two fast clicks, one stale value

The cart had quantity steppers. The decrement handler looked reasonable:

onClick={() => setQuantity(product.id, quantity - 1)}

quantity comes from props. Click twice quickly enough that both events land in
the same React batch and both handlers compute 3 - 1 = 2. The second click
does nothing.

The fix is to stop passing absolute values around and resolve the change inside
the updater, where the latest state is available:

const addItem = useCallback((id, delta = 1) =>
  update((current) => {
    const existing = current.find((line) => line.id === id);
    if (!existing) return delta > 0 ? [...current, { id, quantity: delta }] : current;

    const quantity = existing.quantity + delta;
    return quantity <= 0
      ? current.filter((line) => line.id !== id)
      : current.map((l) => (l.id === id ? { ...l, quantity } : l));
  }), [update]);

Now the buttons call addItem(id, +1) and addItem(id, -1) and two clicks
always add up.

3. A preload that downloaded 64KB on every page that didn't need it

I had put the sensible-looking thing in index.html:

<link rel="preload" as="image" href="/water-texture.webp" type="image/webp" />

This is a single-page app. One index.html serves every route. So /shop,
/cart and every product page were all downloading the hero texture — a texture
that only ever renders on /. The browser even said so in the console:

The resource … was preloaded using link preload but not used within a few
seconds from the window's load event.

I deleted it. The hero's own background-image request starts as soon as React
mounts it, which is soon enough, and nothing else pays for it.

4. Hash links that navigated but never scrolled

Clicking [ABOUT] from /shop should land you on the home page at the About
section. It navigated fine and stayed at the top.

Two reasons, stacked. The target section had not mounted yet when the effect
ran — so document.querySelector(hash) returned null. And once I fixed that
with a retry, a smooth scrollIntoView got cancelled halfway as the hero image
loaded and the page height changed underneath it.

What works is re-asserting the position for a short while instead of firing one
animation and hoping:

useEffect(() => {
  if (!hash) {
    window.scrollTo({ top: 0, behavior: "instant" });
    return;
  }

  let cancelled = false, timer = 0, attempts = 0;

  const settle = () => {
    if (cancelled) return;
    const target = document.querySelector(hash);
    if (target) {
      const top = target.getBoundingClientRect().top + window.scrollY;
      if (Math.abs(window.scrollY - top) > 4) {
        window.scrollTo({ top, behavior: "instant" });
      }
    }
    if (++attempts < 40) timer = window.setTimeout(settle, 50);
  };

  settle();
  return () => { cancelled = true; window.clearTimeout(timer); };
}, [pathname, hash]);

Plain in-page anchors keep the CSS smooth behaviour. Cross-route hashes jump,
which is what a browser does for a hash on load anyway.

Reduced motion is not optional here

A constantly moving water surface is close to the canonical example of what
prefers-reduced-motion exists to prevent. The simulation should not merely be
slower for those users — it should not start at all:

if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) return;

Because it returns before the dynamic import, jQuery never loads either. Those
visitors save about 32KB gzipped and get a clean static background instead.

One detail I nearly shipped: the hero says "CLICK THE WATER" underneath the
headline. Under reduced motion, clicking does nothing. So that line is hidden
too:

@media (prefers-reduced-motion: reduce) {
  .motion-hint { display: none; }
}

Telling someone to click something that will not respond is worse than saying
nothing.

Filming it without a screen recorder

I needed a promo video, and screen recordings come with a cursor, compression
mush, and whatever your OS decides to overlay on them.

So I ported the plugin's shaders to numpy and rendered frames on the CPU. The
update step is four np.roll calls:

avg = 0.25 * (
    np.roll(height, 1, axis=1) + np.roll(height, -1, axis=1)
    + np.roll(height, 1, axis=0) + np.roll(height, -1, axis=0)
)
velocity += (avg - height) * 2.0
velocity *= 0.995
height += velocity

And the render step reduces to a normalised gradient of the height field, which
you use to offset the background lookup.

The first output was wrong in a way I did not expect: the ripples were ovals.

I had made the simulation grid match the output aspect — 512×288 for a 16:9
hero, which felt tidy. But waves propagate one grid cell per step in both axes,
and if your cells are not square in screen space, circles come out stretched.

The plugin does not do that. It runs a square grid and normalises by the
element's longest side:

var longestSide = Math.max(elWidth, elHeight);
radius = radius / longestSide;

Switch to a 512×512 grid covering longestSide² in screen space, display only
the middle band, and the circles come back.

Second surprise: the ripples spread far too slowly. The browser steps the
simulation once per animation frame, roughly 60 times a second. I was stepping
once per rendered frame at 22fps. Three steps per frame and the timing matched
the real thing.

Was it worth it?

For a hero that most visitors will look at for four seconds — probably not, on
any rational accounting.

But every one of those four bugs was a thing I now recognise on sight, and three
of them had nothing to do with water. 100vh on mobile, stale values in a
batched handler, and a preload paying for a page that never uses it are all
going to happen to me again.

The whole thing is packaged up as a template if you want to poke at the source:
ondaris-template.vercel.app

DEV Community: Melis Su Kaya