Installation

npm install ripppl

Usage

import { attachRipple } from "ripppl";

const handle = attachRipple("#my-button", {
  scope: "#card",
  amplitude: 3,
  shimmer: "oklch(0.72 0.19 45)",
});

handle.update({ speed: 400 });
handle.trigger({ x: 0.5, y: 0.5 });
handle.destroy();

attachRipple takes a trigger (CSS selector, element, or list of elements) and optional options. Clicks on the trigger capture the surrounding DOM and run the ripple. Use scope to clip the effect to a container; omit scope for a full-viewport ripple.

The returned handle exposes:

| Method | Purpose | |--------|---------| | update(partial) | Merge new tuning values (see parameters below). | | trigger({ x?, y?, fromElement? }) | Start a ripple at normalized coordinates 0–1 inside the scope, or centered on fromElement. | | invalidateCapture() | Mark the frozen DOM snapshot stale (for example after layout or content changes). The next trigger will capture again unless you prefetch first. | | prefetchCapture() | Start a background capture while the DOM is in a known-good state. Use when you know you will call trigger soon so capture work overlaps with transitions, loaders, or countdowns instead of blocking the first frame of the ripple. | | destroy() | Remove listeners, overlay, and WebGL resources. |

Export RIPPPL_CAPTURE_IGNORE_ATTR: the attribute name (data-ripppl-overlay) placed on the WebGL overlay and on any element that must be omitted from the snapshot. Apply it to temporary UI that should not appear in the captured texture while prefetchCapture runs.

Types: RippleOptions, RippleTuning, RippleHandle are exported from the package.

Parameters

Options passed to attachRipple or update (all optional except where noted):

| Option | Type | Default | Description | |--------|------|---------|-------------| | scope | string | HTMLElement | document.body | Element whose box clips the ripple and capture. | | amplitude | number | 3 | Displacement strength of the wave. | | frequency | number | 0.018 | Spatial frequency of the ripple rings. | | speed | number | 300 | How fast the wave propagates. | | damping | number | 0.025 | Ring falloff behind the wave front. | | decay | number | 1.2 | How quickly the effect fades over time. | | duration | number (ms) | 3500 | Max duration of the animation. | | chromatic | boolean | false | Chromatic aberration on the displaced image. | | chromaticIntensity | number | 0.4 | Strength when chromatic is true. | | shimmer | string | false | false | OKLCH color string for the shimmer pass, or false to disable. | | shimmerWidth | number | 1 | Width of the shimmer band. | | shimmerDuration | number (ms) | 2600 | Shimmer timing relative to the ripple. | | shimmerGlowColor | string | — | Optional OKLCH override for glow highlights (uses shimmer color when omitted). |

Contributing

Issues and pull requests are welcome in GitHub Issues.

Clone the repo, install dependencies, and run the demo or build the library:

git clone https://github.com/Arman-Luthra/ripppl.git
cd ripppl
npm install
npm run dev

npm run build

Please keep changes focused and match existing style. For larger changes, open an issue first so the direction is agreed.

License

MIT