# Water Ripple

Aperveil / Light, shaped for the web.

Collection: Free, available now.

An interactive water ripple background for React: rain rings and the cursor's wake spread over clear water, refracting the floor or your own image, rendered live in WebGPU.

[Aperveil integration guide](https://www.aperveil.com/docs)

## What it does

Water Ripple is clear water seen from above, over a pale stone floor or over an image or video you choose. Every ring is a capillary wave packet, the kind a raindrop makes on a puddle: two to four crests that widen as they travel, the short ones running ahead, fading within a second and a half. Drops fall on their own, the cursor leaves a wake as it moves and a drop where it arrives, and because the waves are linear they simply add up where they meet. You see them the way you see real ripples: the floor bends beneath them, a low sun glints on their slopes, and a slow swell focuses a net of caustic light on the floor that every ring lenses as it passes.

## Choose it for

Give a spa, a swimming school, a summer campaign or a calm product launch a surface that answers the visitor: the hero stays readable over still water, and every move of the cursor sets rings running under the heading.

## Limits

Water Ripple draws its own water over a stone floor or one image or video you choose; it cannot ripple the live HTML of your page, and its waves do not reflect off the edges of the frame. A click is not a separate drop: the cursor's path and its arrival are what touch the water.

## Current look

Default. Color Looks change colors only; motion, geometry and typography remain unchanged.

[Open editor](https://www.aperveil.com/shaders/water-ripple/edit?look=default&scene=landing)

## Landing scene

This preview uses `depth`: 1.15, `caustics`: 0.5, `swell`: 0.55. The editor link carries these settings with your Look. Direct editor visits use the product defaults; Reset all restores those defaults.

## Install

Install editable source with the CLI; it installs shared dependencies automatically. Free needs no login. ZIP Export Kits are also available.

```sh
npx @aperveil/cli add shader water-ripple --framework react
```

Every control in the editor is a typed prop. Leave a prop out to keep the value you exported; change one and the running shader updates without restarting. Give the surface a size and pass fallback for browsers without WebGPU.

```tsx
"use client";

import WaterRipple from "./components/aperveil/water-ripple/WaterRipple";

export default function Hero() {
  return (
    <WaterRipple
      className="hero-shader"
      src="/videos/your-clip.mp4" scale={1} waterColor="#06b2e0"
      fallback={<div className="hero-shader-fallback" />}
    />
  );
}

// .hero-shader { width: 100%; height: 560px; }
```

Component props: `waterColor`, `floorColor`, `lightColor`, `skyColor`, `scale`, `strength`, `depth`, `caustics`, `swell`, `rain`, `gloss`, `flowSpeed`, `interaction`, `tailLength`, `opacity`, `src`, `mediaFocus`, `mediaKind`, `className`, `style`, `paused`, `fallback`, `onReady`, `onError`.

### Vue and Nuxt

```sh
npx @aperveil/cli add shader water-ripple --framework vue
```

```vue
<script setup lang="ts">
import WaterRipple from "./components/aperveil/water-ripple/vue/WaterRipple.vue";
</script>

<template>
  <WaterRipple class="hero-shader" src="/videos/your-clip.mp4" :scale="1" water-color="#06b2e0">
    <template #fallback><div class="hero-shader-fallback" /></template>
  </WaterRipple>
</template>

<!-- .hero-shader { width: 100%; height: 560px; } -->
```

Vue 3.5 or newer, Nuxt included: it renders an empty canvas on the server and starts in the browser, so it needs no <ClientOnly>. Same props as the React component.

### Plain HTML

```html
<script type="module" src="./aperveil-water-ripple.js"></script>

<aperveil-water-ripple class="hero-shader" src="/videos/your-clip.mp4" scale="1" water-color="#06b2e0">
  <div slot="fallback" class="hero-shader-fallback"></div>
</aperveil-water-ripple>

<style>
  .hero-shader { display: block; width: 100%; height: 560px; }
</style>
```

No install and no build step: keep the two files of the kit's html folder together.

### WordPress

Download `aperveil-shader-water-ripple.zip` from the editor (Install, then WordPress) and upload it under Plugins, Add New, Upload Plugin. WordPress 6.5 or newer: a plugin with a block that holds your own content in front of the shader, and a shortcode for page builders. In the block editor, add the "Water Ripple" block (Design) and place your blocks inside it; in a page builder, use the shortcode:

```html
[aperveil_water_ripple height="560px" overlay="20" src="https://example.com/your-clip.mp4"]
  <h2>Your headline</h2>
  <p>Your text, in front of the shader.</p>
[/aperveil_water_ripple]
```

### Framer

Copy `WaterRipple.tsx` from the editor (Install, then Framer); it opens on the values you chose. In Framer, add a new code file (Assets, Code), replace its sample code with the copy, then drag Water Ripple onto the canvas: its Color Looks and every control are in the property panel. [Framer guide](https://www.aperveil.com/docs/framer).

Raw WGSL is included for a custom WebGPU host; it is not CSS. Keep semantic headings and links in HTML.

## Controls

- Water (`waterColor`, color): The color the water takes on with depth, and scatters back.
- Floor (`floorColor`, color): The stone floor under the water. Hidden when an image or video is chosen.
- Sunlight (`lightColor`, color): The sun's glint on the ripples and the caustic light on the floor.
- Sky (`skyColor`, color): The sky the slopes of each ring reflect.
- Ripple size (`scale`, slider): Wavelength and travel of every ring and swell. Larger reads as a closer view.
- Strength (`strength`, slider): How steep the waves are: more refraction, brighter glints, sharper caustics.
- Depth (`depth`, slider): How far below the floor lies. Deeper water bends the floor further, tints it more and focuses the caustics.
- Caustics (`caustics`, slider): The net of focused sunlight on the floor.
- Swell (`swell`, slider): A slow swell from several directions, which draws the caustic net.
- Rain (`rain`, slider): How often drops fall on their own. Zero leaves only the cursor.
- Gloss (`gloss`, slider): Sky and sun reflected in the slopes of the waves.
- Speed (`flowSpeed`, slider): Speed of the swell and the rain.
- Touch (`interaction`, slider): How much water the cursor moves: its wake, and the drop where it arrives.
- Wake length (`tailLength`, slider): How long the cursor's wake keeps spreading after it passes.
- Opacity (`opacity`, slider): Opacity of the whole effect over the page.

## Compatibility

WebGPU rendering requires a supported browser and secure context: Chrome and Edge (Windows, macOS and ChromeOS; Chrome on Android 12 or newer), Safari 26 (Mac, iPhone and iPad) and Firefox (Windows (from 141) and Apple silicon Macs (from 145)). Firefox on Linux, Android and Intel Macs is still rolling it out (checked October 2026). The landing shows a real poster for the selected Look when live rendering is unavailable. The standard exported component does not bundle a poster fallback. Supply your own fallback in the host layout.

## Performance

2.884 ms GPU timestamp median; p95 3.473 ms. 1440x900 @ dpr 1.25; Apple M2 (8-core GPU), Metal driver on macOS Version 26.6.2 (Build 25G83); measured 2026-10-22. This is a recorded headless sample, not a browser FPS or mobile-performance guarantee.

## Questions

### Can I put my own photo under the water?

Yes. Choose an image or video in the editor, or pass one to the component: it lies under the water and every ring refracts it. Depth and the water color set how much the water tints it.

### How is this different from the jQuery Ripples plugin?

It does the same job without a simulation texture: each ring is a capillary wave packet computed in closed form, so drops, the cursor's wake and the swell add up exactly, in WebGPU, with caustics on the floor and the sun's glint on the waves.

### Can it rain on its own?

Yes. Rain sets how often drops fall without the cursor, and zero leaves only the cursor's touch. Swell draws the slow caustic net on the floor; Caustics sets how bright it is.

### What happens without WebGPU?

This landing shows a still poster of your selected Color Look. The raw WGSL needs a WebGPU host. Landing posters are not bundled in the Export Kit: add your own fallback around the exported component.

### Can I use this shader commercially?

Part of the Free collection for Aperveil 1.0. Public live preview and Color Looks are open. Free Export Kits do not require an account. Purchasing is not available yet. Follow the license notices supplied with the source you download. The planned Free collection permits personal and commercial interface projects.

## License

Part of the Free collection for Aperveil 1.0. Public live preview and Color Looks are open. Free Export Kits do not require an account. Purchasing is not available yet. Follow the license notices supplied with the source you download. The planned Free collection permits personal and commercial interface projects.

## Related shaders

- [Caustics](https://www.aperveil.com/shaders/caustics)
- [Ocean Swell](https://www.aperveil.com/shaders/ocean-swell)
- [Frost Glass](https://www.aperveil.com/shaders/frost-glass)