# Ripple Reveal - Skill Reference

> Slideshow that reveals each incoming slide as a soft-edged circle growing from a configurable origin, driven by a CSS `mask` with `radial-gradient` and an animated `@property` custom property.

## What this teaches

- CSS `mask: radial-gradient(...)` to clip a slide by an animatable radius
- `@property --vm-rr-p` registered as `<number>` so `@keyframes` can interpolate it inside `calc()`
- Feather zone: two gradient stops offset from one radius by half of `--vm-rr-feather`
- Params written as `--vm-rr-*` custom properties on the container, so changing a value needs no re-render
- Monotonic `zIndex` counter + `setTimeout` cleanup for slide stacking with no `animationend` listeners
- Ken Burns drift with a long CSS `transition` on the active slide's `img`
- `mount(container, options)` returning a narrow handle (`setParams`, `dispose`) that restores the container

## Core concept

A radial-gradient can't be animated directly, but its stop positions can, if they derive from a registered custom property. `--vm-rr-p` runs 0 to 1 in one `@keyframes` block and every length in the mask is computed from it. The soft edge is the gap between `--vm-rr-edge-in` and `--vm-rr-edge-out`, both offset from the radius by half of the feather, so the edge keeps a constant width while the circle grows, unlike a blur that widens. The max radius is `150%` so the circle clears every corner whatever the origin.

## Use it

### Embed (no build step)

```html
<!-- 1. the script: auto-starts on every [data-ripple-reveal] element -->
<script src="https://vanilla-motion.com/embed/ripple-reveal/1.0.0/ripple-reveal.js"></script>

<!-- 2. the element needs a size: the slideshow fills 100% x 100% of it -->
<div
  data-ripple-reveal
  data-origin-x="0"
  data-origin-y="0"
  data-duration="500"
  data-delay="2000"
  style="width: 100%; aspect-ratio: 16 / 9;"
>
  <!-- slides: every <img> inside the element, in order (any nesting). The effect replaces the
       element's children with its own slides on mount, and dispose() puts these back. -->
  <img src="/img/one.jpg" alt="" />
  <img src="/img/two.jpg" alt="" />
  <img src="/img/three.jpg" alt="" />
</div>
```

- Every key of `defaults` is a kebab-case `data-*` attribute: `originX` becomes `data-origin-x`. All are optional.
- Numbers are read with `Number(...)`. `ease` and `background` are kept as strings. There are no boolean params.
- Images come from the `<img>` children (`currentSrc || src`). The embed has no attribute for an image list and the effect exports no `optionsFromElement`.
- With fewer than 2 slides nothing animates.
- The script exposes `window.RippleReveal` with `init(root)` (start any `[data-ripple-reveal]` added later, e.g. after injecting HTML) and `get(el)` (the running handle for an element), plus `mount`, `defaults` and the `RippleReveal` class.

```js
RippleReveal.get(document.querySelector("[data-ripple-reveal]"))?.setParams({ feather: 40 });
```

The embed does not check `prefers-reduced-motion`. To honour it, omit `data-ripple-reveal` and call `RippleReveal.mount(el)` only when motion is allowed (see Accessibility).

### Bundled apps

Fetch the files into your project:

```bash
npx vanilla-motion add ripple-reveal   # writes ./vanilla-motion/ripple-reveal/
```

```ts
import { mount } from "./vanilla-motion/ripple-reveal/ripple-reveal";

const container = document.querySelector<HTMLElement>("#hero")!; // must have a size

// images: slide URLs. Omit it to use the <img> elements already inside the container.
const fx = mount(container, {
  images: ["/img/one.jpg", "/img/two.jpg", "/img/three.jpg"],
  originX: 0,
  originY: 0,
  duration: 500,
});

fx.setParams({ feather: 40, ease: "linear" }); // partial update; changing `delay` restarts the timer
fx.dispose();                                   // stops timers, removes the vars, restores the original children
```

Handle (`RippleRevealHandle`):

```ts
interface RippleRevealHandle {
  setParams(next: Partial<RippleRevealParams>): void;
  dispose(): void;
}
```

Options are `Partial<RippleRevealParams> & { images?: string[] }`. `images` is not a param: it cannot be set with `setParams`. The module also exports `defaults`, `RippleReveal` (with `static readonly version = "1.0.0"`), and the types `RippleRevealParams`, `RippleRevealOptions`, `RippleRevealHandle`.

### Params

| Key | Default | Range / options | Meaning |
|---|---|---|---|
| `delay` | `5000` | 500 to 10000, step 100 (ms) | Time a slide stays before the next one ripples in. |
| `duration` | `1000` | 100 to 4000, step 50 (ms) | Length of one reveal. |
| `feather` | `20` | 0 to 100, step 1 (% of the element) | Width of the soft edge. `0` is a hard circle. |
| `originX` | `50` | 0 to 100, step 1 (%) | Where the ripple starts across the width. `0` is the left edge, `100` the right. |
| `originY` | `50` | 0 to 100, step 1 (%) | Where the ripple starts down the height. `0` is the top edge, `100` the bottom. |
| `ease` | `"cubic-bezier(0.4, 0, 1, 1)"` | `"cubic-bezier(0.4, 0, 1, 1)"` (ease in), `"linear"`, `"cubic-bezier(0, 0, 0.2, 1)"` (ease out), `"cubic-bezier(0.65, 0, 0.35, 1)"` (ease in out) | CSS timing function of the expansion. Any valid CSS timing function also works in code. |
| `zoom` | `1.1` | 1 to 1.5, step 0.01 | Scale the active slide's image drifts to over 10 s. `1` turns the drift off. |
| `background` | `"#0a372a"` | `#RRGGBB` colour | Colour behind the slides. |

Ranges are the editor's slider limits; the class does not clamp.

## Key code

### HTML structure

```html
<!-- the container gets class vm-ripple-reveal and the --vm-rr-* vars; children are generated -->
<div class="vm-ripple-reveal" style="--vm-rr-x:50%; --vm-rr-y:50%; --vm-rr-feather:20%; ...">
  <!-- first slide has z-index:1 inline so it shows before the first frame; the class "active" is
       added on the next animation frame -->
  <div class="vm-ripple-reveal__slide active" style="z-index:1"><img src="..." alt="" /></div>
  <div class="vm-ripple-reveal__slide"><img src="..." alt="" /></div>
</div>
```

### CSS — the effect

The class injects this once as `<style id="vm-ripple-reveal-style">` (prefixed classes, nothing global).

```css
/* <number>, not <percentage>: a registered number can be interpolated by @keyframes and used inside calc() */
@property --vm-rr-p { syntax: "<number>"; inherits: false; initial-value: 0; }

@keyframes vm-ripple-reveal {
  from { --vm-rr-p: 0; }
  to   { --vm-rr-p: 1; }
}

.vm-ripple-reveal > .vm-ripple-reveal__slide { position: absolute; inset: 0; } /* all slides stacked */

.vm-ripple-reveal img {
  object-fit: cover;
  transform: scale(1);
  transition: transform 10s linear; /* 10 s on a short hold: a barely visible drift (Ken Burns) */
}
.vm-ripple-reveal > .active img { transform: scale(var(--vm-rr-zoom)); }

.vm-ripple-reveal > .active {
  --vm-rr-radius:   calc(var(--vm-rr-p) * 150%);                          /* 150% clears every corner */
  --vm-rr-edge-in:  calc(var(--vm-rr-radius) - var(--vm-rr-feather) / 2); /* opaque up to here */
  --vm-rr-edge-out: calc(var(--vm-rr-radius) + var(--vm-rr-feather) / 2); /* transparent from here */
  mask: radial-gradient(circle at var(--vm-rr-x) var(--vm-rr-y), #000 var(--vm-rr-edge-in), transparent var(--vm-rr-edge-out));
  animation: vm-ripple-reveal var(--vm-rr-duration) var(--vm-rr-ease) forwards; /* easing lives here, not in the keyframes */
}
```

Params map to custom properties on the container (`applyStyle`): `background` to `--vm-rr-bg`, `originX` / `originY` to `--vm-rr-x` / `--vm-rr-y` (as `%`), `feather` to `--vm-rr-feather` (`%`), `duration` to `--vm-rr-duration` (`ms`), `ease` to `--vm-rr-ease`, `zoom` to `--vm-rr-zoom`. `delay` stays in JS.

### JS — state machine

```ts
// timer: every `delay` ms promote the next slide; restarted by setParams when `delay` changes
this.timer = window.setInterval(() => this.setActive((this.current + 1) % this.slides.length), delay);

private setActive(idx: number) {
  const prev = this.current;
  this.current = idx;
  const slide = this.slides[idx];
  slide.style.zIndex = String(++this.zCounter); // monotonic: the incoming slide always paints on top
  slide.classList.remove("active");
  void slide.offsetWidth;                       // force reflow so the keyframes restart
  slide.classList.add("active");

  // drop the previous slide once the new one fully covers it (duration + 200 ms margin)
  const id = window.setTimeout(() => {
    this.cleanups.delete(id);
    if (prev === idx) return;
    this.slides[prev].classList.remove("active");
    this.slides[prev].style.zIndex = "0";
  }, duration + 200);
  this.cleanups.add(id); // tracked so dispose() can clear pending timeouts
}
```

`dispose()` clears the interval, the pending frame and timeouts, removes the class and the `--vm-rr-*` vars, and puts the original child nodes back.

## Variants

### Centre (default)
Ripple from the middle: `originX: 50`, `originY: 50`, with the default 1000 ms reveal and a new slide every `3000` ms. The farthest corners are reached last.

### Top left (top-left)
`originX: 0`, `originY: 0`, `duration: 500`, `delay: 2000`. The circle is centred on the top-left corner, so it sweeps the frame as a quarter circle and the faster reveal reads as a wipe. The `150%` radius still clears the opposite corner.

## Adapt to your layout

- **Origin**: any point from `0` to `100` on each axis; map it to a click or pointer position with `setParams({ originX, originY })` before the next reveal.
- **Edge**: raise `feather` for a blurrier ring, `0` for a hard circle wipe.
- **Speed**: `duration` is the reveal, `delay` is the hold. Keep `delay` above `duration`, or the next ripple starts before the last one ends.
- **Drift**: `zoom: 1` removes the image scale; the `10s` transition length is fixed in the CSS.
- **Size**: the root is `width: 100%; height: 100%` with `overflow: hidden`, so size the container itself (height, `aspect-ratio`) and it crops images with `object-fit: cover`.
- **Updates**: `setParams` changes values the next reveal reads, with no per-frame work.

## Browser support

`@property` (Chromium 85+, Firefox 128+, Safari 16.4+) · CSS `mask` with `radial-gradient` (all modern browsers; older WebKit may need `-webkit-mask`, which the effect does not add) · No polyfill path: feature-detect with `CSS.supports('@property', '--x')` if needed. Without `@property` the first slide is shown and later slides appear without the ripple.

## Accessibility

```ts
// the class does not check this itself: skip mounting so slides never auto-advance
if (!window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
  mount(container, { images });
}
```

Don't just shorten the duration: skip the animation. Slides use `alt=""` (decorative) when the class builds them from `images`; put real content in text next to the slideshow, not in the slide images.