# distortion-wave > A WebGL2 wave that carries any DOM element from one state to the next, with an API shaped like document.startViewTransition(). npm: distortion-wave. Source: https://github.com/LukyVj/distortion-wave ![distortion-wave](docs/brand/banner.png) # distortion-wave A distortion-wave transition for **any DOM element**. A button, a card, a tab panel, the whole page. You give it an element and a function that changes the DOM. It captures the element before and after, then one WebGL2 pass carries the old state into the new one: the screen gets pulled toward the source, a lensed, blurred, colourful wave leaves from where you touched, and its colour lingers on the edges. ![The wave crossing a payment screen](docs/preview.png) Inspired by Jakub Antalik's [Distortion Waves](https://libraries.dev/waves) for SwiftUI. This is an independent web implementation, not affiliated with libraries.dev. - Zero dependencies, ~17 kB gzipped - Same model as `document.startViewTransition()` - Your update **always** runs: no WebGL, element off screen, reduced motion, capture error… you just get the change without the wave - Keyboard focus is kept when your update replaces the focused control ## Install ```sh npm i distortion-wave ``` From a CDN, no build step (CodePen, a plain HTML page…): ```html ``` Or the IIFE build, which exposes `window.DistortionWave`: ```html ``` ### Everything, or only the looks you use The wave (the core) is always there. Each other look (see [Effects](#effects)) is its own entry, so you only pay for the ones you use. | Entry | Gzipped | What's in it | |---|---|---| | `distortion-wave` | 17.0 kB | the wave, the API, every option | | `distortion-wave/electric` | 5.8 kB | `electric`, `electricBorder` | | `distortion-wave/pixel` | 1.2 kB | `pixel` | | `distortion-wave/glass` | 1.0 kB | `glass` | | `distortion-wave/burn` | 1.3 kB | `burn` | | `distortion-wave/ink` | 1.2 kB | `ink` | | `distortion-wave/halftone` | 1.0 kB | `halftone` | | `distortion-wave/metal` | 1.1 kB | `metal` | | `distortion-wave/water` | 1.2 kB | `water` | | `distortion-wave/vine` | 2.9 kB | `vine` | | `distortion-wave/christmas` | 2.6 kB | `christmas` | | `distortion-wave/all` | 28.7 kB | the core and every look | **Only some looks, with a bundler.** Import the core, then each look from its own entry. Only what you import ships: here 17 + 1.3 + 1.2 kB. ```js import { distortionWave } from 'distortion-wave'; import { burn } from 'distortion-wave/burn'; import { water } from 'distortion-wave/water'; distortionWave(card, update, { effect: burn }); ``` **Everything, with a bundler.** One import, every look: ```js import { distortionWave, burn, glass, water } from 'distortion-wave/all'; ``` **Only some looks, without a bundler.** Load the core's IIFE, then the IIFE of each look. Each look sets its own global (`DistortionWaveBurn`, `DistortionWaveGlass`…): ```html ``` **Everything, without a bundler.** `all.iife.min.js` puts the core and every look on `window.DistortionWave`: ```html ``` **One file to host yourself.** On the site, the Install section has a download builder: tick the looks you want, and it gives you a single file with the core and those looks, all on `window.DistortionWave`, with its size. Ticking every look gives the `all` build. ## Usage ```js import { distortionWave, warmupWave } from 'distortion-wave'; warmupWave(); // optional: compiles the shaders before the first click confirmButton.addEventListener('click', (event) => { distortionWave(screen, () => { screen.dataset.state = 'sent'; // any DOM change: classes, innerHTML, a re-render… }, { source: confirmButton, // where the wave starts focus: event, // the touch point: the wave leaves from there and leans that way }); }); ``` The source can be inside or outside the target. When it is outside, the wave enters from that edge and travels toward the bulk of the target. ### A single button ```js button.addEventListener('click', (event) => { distortionWave(button, () => { button.textContent = 'Subscribed'; }, { focus: event }); // no source: a ring from the touch point }); ``` ### The whole page (theme switch) ```js themeSwitch.addEventListener('click', (event) => { distortionWave(document.querySelector('#app'), () => { app.dataset.theme = app.dataset.theme === 'dark' ? 'light' : 'dark'; }, { source: themeSwitch, focus: event }); }); ``` Only the part visible in the viewport is captured and animated, so a long page costs the same as a screen. ### React The DOM has to be updated when your callback returns, so the state change goes through `flushSync` (same as with View Transitions). A small hook keeps that in one place: ```jsx import { useCallback } from 'react'; import { flushSync } from 'react-dom'; import { distortionWave } from 'distortion-wave'; export function useWave(defaults) { return useCallback((target, update, options) => { const el = target && 'current' in target ? target.current : target; if (!el) { update(); return null; } return distortionWave(el, () => flushSync(update), { ...defaults, ...options }); }, [defaults]); } ``` ```jsx function Pricing() { const wave = useWave(); const panel = useRef(null); const [plan, setPlan] = useState('monthly'); return ( <>
{plan === 'yearly' ? : }
); } ``` Pass `defaults` from a `useMemo` (or a constant) so the callback stays stable. The full example is in [`examples/react/`](examples/react/). ### Shortcut ```js import { waveOnClick } from 'distortion-wave'; waveOnClick(trigger, target, (event) => { /* update */ }, { palette: 'ocean' }); ``` `waveOnClick` also pre-captures the target when the pointer enters the trigger or it gets focus, so the "before" capture costs nothing at click time. ## Effects Effects change the look of the wave, not its behaviour. The wave is built in; other looks ship as their own entry, so the core stays at ~17 kB gzipped when you don't use them. ### Electric `distortion-wave/electric` (~6 kB gzipped) brings the electric look, for the wave and as a border. ```js import { distortionWave } from 'distortion-wave'; import { electric, electricBorder } from 'distortion-wave/electric'; // The same wave (timing, lens, blur, sparks) with an electric look: the front is a crackling bolt, // the colour band goes electric, the outline charges with arcs as the front passes distortionWave(card, update, { effect: electric, source: button, focus: event }); // A live arc on the outline, rounded corners included const border = electricBorder(card, { trigger: 'hover', color: '#7df9ff' }); border.destroy(); // fades out, removes the listeners ``` Without a bundler: `https://cdn.jsdelivr.net/npm/distortion-wave@0.4/dist/electric.js` (ES module, no imports of its own), or `dist/electric.iife.min.js` for `window.DistortionWaveElectric`. **With `effect: electric`** every wave option works the same (`source`, `focus`, `variant`, `duration`, `easing`, `palette`, `particles`, the fine-tuning keys…). The default palette becomes `'electric'`. Its own keys, at the same reference scale: | Key | Default | | |---|---|---| | `jag` | `8` px | how jagged the front is | | `scale` | `46` px | one noise cell along the front; smaller is more jagged | | `crackle` | `1.8` | speed of the crackle | | `chaos` | `6` px | how far the bolts stray from the front | | `boltWidth`, `boltGlow` | `1.5`, `14` px | bright core of a bolt, glow around it | | `bolts`, `rimBolts` | `1.2`, `1.3` | strength of the bolts on the front, of the arcs on the outline (0 = none) | `intensity` also scales `jag` and `chaos`. **Border options**: `color` or `palette` (default `'electric'`), `trigger` (`'always'`, `'hover'`, `'focus'`, `'hover focus'`, `'manual'`), `thickness`, `glow`, `chaos`, `scale`, `crackle`, `offset`, `intensity`, `fadeIn`, `fadeOut`, `zIndex`. The controller has `start()`, `stop()`, `set(options)`, `destroy()` and `active`. Every border of the page draws in one shared canvas: a grid of cards costs one WebGL context. With `prefers-reduced-motion`, the arc stays still. ### Pixel `distortion-wave/pixel` (~1.2 kB gzipped): the same wave with a pixel look. Near the front, the content turns into small pixels that flip from the old state to the new one cell by cell; some light up in the palette and flicker; the outline is drawn in pixels that go out one by one; sparks are square. Default palette `'pixel'` (orange). ```js import { pixel } from 'distortion-wave/pixel'; distortionWave(card, update, { effect: pixel, source: button, focus: event }); ``` | Key | Default | | |---|---|---| | `cell`, `gap` | `6`, `1` px | size of a pixel, gap between pixels (0 = a plain mosaic) | | `zone` | `1` | width of the pixel zone around the front, × the band's `lead` | | `density` | `0.45` | share of lit pixels at the front | | `rate` | `14` | flicker, changes per second | | `lit`, `rimPixels` | `1`, `1` | strength of the lit pixels, of the pixels on the outline (0 = none) | CDN: `https://cdn.jsdelivr.net/npm/distortion-wave@0.4/dist/pixel.js`, or `dist/pixel.iife.min.js` for `window.DistortionWavePixel`. ### More looks Eight more entries, each about 1 to 3 kB gzipped, same pattern: `import { glass } from 'distortion-wave/glass'`, then `effect: glass`. Every wave option still applies; each look adds its own keys (sizes at the 360 × 740 reference scale) and exports their defaults (`GLASS`, `BURN`, `INK`, `HALFTONE`, `METAL`, `WATER`, `VINE`, `CHRISTMAS`). A key shared by two looks means the same thing in both. A look can also bring its own spark shape (vine's sparks are leaves, christmas's are snowflakes). **`distortion-wave/glass`** (~1.0 kB gzipped, `window.DistortionWaveGlass` from `dist/glass.iife.min.js`). Behind the front a thick slab of glass bends the content like a lens, splits it into RGB at its slopes and catches the light on its faces. Pale glass palette. | Key | Default | | |---|---|---| | `thickness` | `90` px | width of the slab behind the front | | `refraction`, `dispersion` | `26`, `5` px | how far the slab bends what's under it, RGB split at its slopes | | `shine`, `tint` | `1`, `0.25` | highlights, palette tint of the glass (0 = none, clear) | **`distortion-wave/burn`** (~1.3 kB gzipped, `window.DistortionWaveBurn` from `dist/burn.iife.min.js`). The front burns the old content away along a ragged edge pinned to the content: scorch ahead, a white-hot rim, smoke and embers drifting up behind. Made for a delete. Palette `'ember'`. | Key | Default | | |---|---|---| | `roughness`, `scale` | `32`, `100` px | how ragged the edge is, one noise cell | | `char`, `heat` | `70`, `11` px | scorched zone ahead, width of the glowing edge | | `embers`, `smoke` | `1`, `0.5` | embers and smoke behind the edge (0 = none) | **`distortion-wave/ink`** (~1.3 kB gzipped, `window.DistortionWaveInk` from `dist/ink.iife.min.js`). Risograph. The front bleeds like ink soaking into paper; around it the content is reprinted in two inks (the palette's first two colours), out of register, dithered by the paper's grain. Riso palette (fluorescent pink, blue, yellow, green). | Key | Default | | |---|---|---| | `bleed`, `scale` | `30`, `110` px | how far the ink spreads, one noise cell | | `misregister`, `ink` | `3`, `36` px | offset between the two inks, width of the wet ink behind the front | | `grain`, `zone` | `1`, `1.2` | paper grain (0 to 1), printed zone × the band's `lead` | **`distortion-wave/halftone`** (~1.0 kB gzipped, `window.DistortionWaveHalftone` from `dist/halftone.iife.min.js`). Near the front the content turns into a rotated dot screen: dark dots on light content, light dots on dark, sized by its tone, swelling with the wave and inked in the palette at its peak. CMYK-like palette. | Key | Default | | |---|---|---| | `cell`, `angle` | `7` px, `45`° | one cell of the screen, its angle | | `zone`, `size` | `1.1`, `1.2` | screen zone × the band's `lead`, largest dot × the cell | | `ink` | `0.7` | palette ink at the front (0 = the content's own colours) | **`distortion-wave/metal`** (~1.1 kB gzipped, `window.DistortionWaveMetal` from `dist/metal.iife.min.js`). Liquid metal. The front is a rolling bead of chrome that wobbles, mirrors a procedural studio and, faintly, the content. Best on a dark page. Chrome palette that tints the reflections. | Key | Default | | |---|---|---| | `thickness`, `wobble` | `46`, `14` px | width of the bead, slow wobble of the front | | `ripple`, `shine` | `0.6`, `1` | ripples on the surface, specular highlight | | `reflect` | `0.35` | how much of the content the metal mirrors (0 to 1) | **`distortion-wave/water`** (~1.2 kB gzipped, `window.DistortionWaveWater` from `dist/water.iife.min.js`). Ripples trail the front and refract the content, the water tints it, caustics dance on it and foam breaks on the front. Palette `'ocean'`. | Key | Default | | |---|---|---| | `wavelength`, `refraction` | `44`, `9` px | distance between ripples, how far they bend the content | | `caustics`, `foam` | `1`, `1` | light patterns, foam on the front (0 = none) | | `tint` | `0.35` | palette tint of the water (0 = clear) | **`distortion-wave/vine`** (~2.9 kB gzipped, `window.DistortionWaveVine` from `dist/vine.iife.min.js`). Plants. The front is a band of leaves with leafy bumps, green leaves fall behind it, a vine grows around the element as the front passes, and the sparks are leaves. Green palette. | Key | Default | | |---|---|---| | `leaf`, `zone` | `26` px, `0.8` | leaf size, depth of the foliage around the front | | `bumps` | `14` | leafy bumps along the front (0 = smooth) | | `fall`, `vine` | `1`, `1` | falling leaves, the vine around the element (0 = none) | | `vineWidth` | `2.5` px | width of the stem | **`distortion-wave/christmas`** (~2.6 kB gzipped, `window.DistortionWaveChristmas` from `dist/christmas.iife.min.js`). The front is a twisted candy cane with frost and glints ahead of it, snow falls behind it, a string of lights hangs along the outline and twinkles, snow and icicles settle on the top edge, and the sparks are snowflakes. Red, white, green and gold palette. | Key | Default | | |---|---|---| | `cane`, `stripe` | `7`, `16` px | radius of the candy cane, width of its stripes | | `snow`, `flake` | `1`, `3` px | snowfall behind the front (0 = none), size of a flake | | `lights`, `bulbs` | `1`, `30` px | the string of lights (0 = none), distance between bulbs | | `cap` | `11` px | snow on the top edge, with icicles (0 = none) | | `frost` | `0.6` | frost and glints ahead of the front | ## Examples - [`demo/`](demo/): a payment screen, a single button, a tab panel, a media card, an element that changes size and a whole-page theme switch. - [`examples/ui-kit/`](examples/ui-kit/): about 40 clickable UI pieces in five groups (buttons, toggles and selection, commerce, navigation and content, forms and feedback), plus a theme switch that waves the whole page and an Options panel (duration, easing, intensity, palette). `index.html`, `style.css` and `script.js` paste straight into CodePen; `standalone.html` opens from disk. - [`examples/react/`](examples/react/): React 19 + Vite, with the `useWave` hook, a like button, tabs, a list that grows, a theme switch and live options. `npm install && npm run dev` in that folder. `codepen.jsx` is the same app for CodePen (JS preprocessor: Babel). ## AI agents [`skill/`](skill/) holds an Agent Skill for coding agents (Claude Code, Cursor, Codex…): how to pick the target and the source, framework patterns, options, troubleshooting, and a script that films a wave frame by frame. Install notes in [`skill/README.md`](skill/README.md). ## API ### `distortionWave(target, update?, options?) → WaveTransition` | Option | Default | | |---|---|---| | `source` | touch point, else center | where the wave starts: an `Element` (inside or outside the target), a `DOMRect` or `{ x, y }` | | `focus` | `null` | the `PointerEvent`/`MouseEvent` (or `{ x, y }`): the wave leans toward it. Keyboard clicks are ignored | | `variant` | `'auto'` | `'vertical'`, `'horizontal'`, `'center'`. Auto: wide source → vertical, tall → horizontal, square or point → center | | `palette` | `'aurora'` | `'aurora'`, `'ocean'`, `'mint'`, `'ember'`, or up to 8 colours (interpolated in OKLab) | | `duration` | auto | total length in ms, until `finished`. By default it depends on the size: about 2 s for a button, 4 s for a whole page, the last half being the glow fading out | | `easing` | `'cubic-bezier(0.2, 1, 0.3, 1)'` | how the front travels: a CSS keyword (`'linear'`, `'ease-out'`…), `'cubic-bezier(…)'`, `[x1, y1, x2, y2]` or a function | | `speed` | `1` | time multiplier on the automatic duration (`0.3` = slow motion). Ignored when `duration` is set | | `intensity` | `1` | strength of the distortion (displacement, bulge, chromatic aberration). `0` keeps only the colours | | `particles` | `true` | `false`, or a count | | `reducedMotion` | follows `prefers-reduced-motion` | `true` gives a 220 ms crossfade | | `preserveFocus` | `true` | move focus to the equivalent control if the update replaced the focused one | | `timeout` | `3000` | max ms to wait for the "after" capture | | `onLaunch`, `onCovered`, `onSettled`, `onEnd(metrics)` | | callbacks | ```js distortionWave(card, update, { duration: 1400, easing: 'ease-in-out', intensity: 0.5, palette: ['#ff5a7a', '#ffffff'] }); ``` **Defaults for the whole app.** `setWaveDefaults({ duration: 900, palette: 'ocean' })` applies to every wave; options passed to a call still win. `setWaveDefaults(null)` resets.
Fine tuning: every key of the presets Values are given for a 360×740 screen and scaled to the target, so a button gets a thinner rim and a shorter wave. Lengths in px, times in seconds (all times are stretched together when you set `duration`). | Key | Default | | |---|---|---| | `anticipation` | `0.45` | the "inhale" before the wave leaves the source | | `travel` | `2.2` | time for the front to cross the target | | `linger`, `rimFade` | `-0.3`, `2.8` | when the glowing edge starts to clear (relative to the end of the travel), and how long it takes | | `amplitude` | `32` | displacement under the front | | `lensWidth` | `140` | width of the lens band | | `swell` | `20` | how much the front bulges outward | | `aberration` | `0.75` | chromatic split | | `blur`, `blurNear` | `18`, `6` | max blur, and the blur right next to the front | | `blurAhead`, `blurBehind` | `90`, `230` | how far the blur reaches before and after the front | | `lead`, `tail`, `band` | `120`, `280`, `0.9` | the colour band: length ahead, length behind, strength | | `rimWidth`, `rimSoftness`, `rimStrength` | `14`, `320`, `0.85` | the glow on the element's edge | | `hairWidth` | `1.5` | the thin line on the edge | | `lean` | `0.9` | how much the front tilts toward the touch point (0 to 1) | | `pull`, `inhale` | `22`, `50` | how much the content is pulled toward the source during the anticipation | | `particleSize`, `particleLife`, `reach`, `spread` | `1.8`, `2.1`, `140`, `1` | the sparks | The `center` variant has its own values: see `PRESETS.center`.
`WaveTransition` mirrors `ViewTransition`: | | | |---|---| | `ready` | the overlay is up and animating | | `updateCallbackDone` | your update finished (rejects if it threw) | | `covered` | the old state is no longer visible | | `finished` | the overlay is gone, the real DOM is back | | `skip()` | jump to the end (the update still runs) | | `metrics` | `{ captureBefore, captureAfter, upload, worstFrame }` in ms | ### Other exports - `setWaveDefaults(options)`: options for every wave (see above). - `warmupWave()`: creates a WebGL context and compiles the shaders ahead of time. - `prepareWave(target)`: pre-captures a target. Invalidated by any mutation. - `snapshotElement(el, { dpr, clip })`: the DOM → canvas capture on its own. - `PALETTES`, `PRESETS`, `scaleConfig`, `totalDuration`, `frameState`: the pure core, if you want to drive your own renderer. - `distortion-wave/electric`: `electric`, `electricBorder`, `ELECTRIC`, `BORDER` (see Effects). - `distortion-wave/pixel`: `pixel`, `PIXEL` (see Effects). - `distortion-wave/all`: everything above and every effect, in one entry. - `distortion-wave/glass`, `/burn`, `/ink`, `/halftone`, `/metal`, `/water`, `/vine`, `/christmas`: the look and its defaults, like `glass` and `GLASS` (see More looks). ## How it works 1. **Capture.** The element is cloned with every node's computed style inlined (pseudo-elements, form state, open shadow DOM, images and fonts turned into data URLs), serialized into an SVG ``, and rasterized by the browser itself. 2. **Update.** The real element goes `opacity: 0` (it stays focusable and in the accessibility tree), a canvas sits on top, and your update runs during the anticipation. 3. **Capture again**, then build a blur pyramid once: sharp, near and far. 4. **One full-screen pass per frame.** A signed distance field gives the wave front. Around it the shader stacks a lens along the normal, chromatic aberration, a progressive blur blended from the pyramid, a colour band in OKLab, a rim on the element's own rounded corners, and dithering. Particles are drawn as points. 5. **Hand back.** As soon as the lens and blur are gone, the real element is shown again under the canvas and becomes interactive. The canvas only paints the lingering rim, then leaves. All the timing lives in a pure function, `frameState(t, config, geometry)`. The GPU only paints, so any frame can be reproduced and tested. ## Performance Capture times measured in headless Chrome at DPR 1, warm: a button ~2 ms, a card ~9 ms, a phone-sized screen ~13 ms, a whole app UI (100+ nodes) 50–75 ms. The anticipation phase hides them. The rendering cost is one full-screen pass per frame (up to ~18 texture reads per pixel near the wave front, far fewer elsewhere). The DPR is capped at 2 and textures at ~4 Mpx. Up to 4 WebGL contexts are pooled and reused. ### Bundle size The core is ~17 kB gzipped, shaders included; each look adds 1 to 6 kB (see [Everything, or only the looks you use](#everything-or-only-the-looks-you-use)). If the wave only plays on a few interactions, keep it out of the initial bundle and load it on the first one: ```js let lib; const load = () => (lib ??= import('distortion-wave').catch(() => null)); button.addEventListener('pointerenter', load, { once: true }); // starts the download on hover button.addEventListener('click', async (e) => { const dw = await load(); if (!dw) return render(next); // offline or blocked: just update dw.distortionWave(card, () => render(next), { source: button, focus: e }); }); ``` On touch screens `pointerdown` comes before `click`, so the download starts there too. Bundlers split the dynamic `import()` into its own chunk. ## Accessibility - `prefers-reduced-motion` gives a short crossfade, no distortion. - The trigger stays a real `
{plan === 'yearly' ? : }
); } ``` - Pass `defaults` from `useMemo` or a module constant, or the callback changes on every render. - Use `e.currentTarget` (the button), not `e.target` (maybe an icon inside it). - Don't call `distortionWave` during render or in a `useEffect` that reacts to the state change: by then the DOM already shows the new state, and the "before" snapshot would be wrong. Call it from the event handler that causes the change. - `useTransition` / `startTransition` defer the render: don't use them inside `update`. - Next.js App Router: the component that calls it needs `'use client'`. Importing the package on the server is harmless (no side effects). - A full example lives in the package repo: `examples/react/` (React 19 + Vite) and `examples/react/codepen.jsx`. ## Vue 3 Set the state, then return `nextTick()`: ```js // useWave.js import { nextTick, unref } from 'vue'; import { distortionWave } from 'distortion-wave'; export function useWave(defaults = {}) { return (target, update, options) => { const t = unref(target); const el = t?.$el ?? t; // template ref to an element or a component if (!el) return update(); return distortionWave(el, async () => { await update(); await nextTick(); }, { ...defaults, ...options }); }; } ``` ```vue ``` `` on the same element would animate twice: pick one. ## Svelte 5 ```svelte
{plan}
``` Svelte 4: same thing with `on:click` and a plain `let`. ## Angular Run change detection inside `update`: ```ts @ViewChild('panel') panel!: ElementRef; plan = signal('monthly'); constructor(private cdr: ChangeDetectorRef) {} pick(e: MouseEvent, p: string) { if (this.plan() === p) return; distortionWave(this.panel.nativeElement, () => { this.plan.set(p); this.cdr.detectChanges(); }, { source: e.currentTarget as Element, focus: e }); } ``` Works the same with plain fields instead of signals. ## Solid Signals update the DOM synchronously, so set them and you are done: `distortionWave(panel, () => setPlan(p), { source: e.currentTarget, focus: e })`. Don't wrap the update in `startTransition`. ## Lit and web components ```js pick(e, p) { distortionWave(this.renderRoot.querySelector('.panel'), async () => { this.plan = p; await this.updateComplete; }, { source: e.currentTarget, focus: e }); } ``` Open shadow roots inside the target are captured. Closed shadow roots are not. ## htmx and server-rendered HTML Fetch first, then swap inside `update`, so the wave never waits on the network: ```js const html = await (await fetch('/cart/summary')).text(); distortionWave(summary, () => { summary.innerHTML = html; }, { source: button, focus: e, palette: 'mint' }); ``` With htmx, take over the swap for elements you mark: ```js document.body.addEventListener('htmx:beforeSwap', (evt) => { const target = evt.detail.target; if (!target.matches('[data-wave]')) return; evt.detail.shouldSwap = false; distortionWave(target, () => { target.innerHTML = evt.detail.serverResponse; htmx.process(target); }); }); ``` This handles `innerHTML` swaps only: other `hx-swap` strategies need their own DOM code. --- # Recipes Each line is a component from the official UI kit (`examples/ui-kit` in the package repo, about 40 pieces). The code for all of them is in `examples/ui-kit/script.js`. ## Contents - Choosing target and source, per component - Copy with a label that reverts - Two states in a row - Form submit - Theme switch on the whole page - Route change in a single-page app - Swapping an image - Keyboard and focus - App-wide settings ## Choosing target and source, per component | Component | target | source | Notes | |---|---|---|---| | Like, bookmark, mute, follow, status pill | the button | none | ring from the touch point; palette by meaning (ember for like, mint for success) | | Filter chip, checklist item | the chip or item | none | | | Vote up/down | the vote group | the arrow pressed | the wave leaves the arrow | | Settings row with a switch | the row | the switch | the subtitle text changes too, so the row is the target | | Radio cards, segmented control | the group | the chosen card | return early when it is already selected | | Star rating | the rating block | the star clicked | custom palette: `['#ffc53d', '#ff9f43', '#ff6b6b']` | | Colour swatch → preview | the preview | the swatch | `palette: [colour, '#ffffff', colour]` | | Toolbar → paragraph (text align) | the paragraph | the toolbar button | the source sits outside the target | | Add to cart | the product card | the button | update the header badge in the same `update`, without its own wave | | Quantity stepper | the stepper | `+` or `−` | return early at the bounds: no wave when nothing changes | | Wishlist heart on a card | the card | the heart | | | Currency or unit switch | the list of prices / the value | the switch | `innerHTML` re-render is fine | | Tabs | the panel | the tab | not the tab bar | | Pagination | the list | the page button | the source is below the target: the wave goes up | | Accordion | the whole accordion | the header | the size changes; the outline of the wave follows | | Flashcard | the card | its button | two clicks, two waves (question → answer → next) | | Delete → Undo row | the row | the button | `innerHTML` is replaced; focus lands on the new button | | Order progress, steps | the steps row | "Next step" | a transparent row: the wave lights the content only (≥ 0.1.1) | | Notifications "mark all read" | the list | the button | | | Chat composer | the thread | Send | the thread grows | | Media player | the player | play/pause | | | Options panel open/close | the panel wrapper | the toggle | | ## Copy with a label that reverts ```js copy.addEventListener('click', (e) => { navigator.clipboard?.writeText(code.textContent); distortionWave(codeBlock, () => { copy.textContent = 'Copied!'; }, { source: copy, focus: e, palette: 'mint' }) .finished.then(() => setTimeout(() => { copy.textContent = 'Copy'; }, 1200)); // revert without a wave }); ``` ## Two states in a row ```js dl.addEventListener('click', async (e) => { await distortionWave(dl, () => setLabel('Downloading…'), { focus: e, palette: 'ocean' }).finished; await download(); // the real work, between the two waves distortionWave(dl, () => setLabel('Downloaded'), { palette: 'mint' }); }); ``` ## Form submit `submit` has no coordinates, and Enter in a field must work too. Remember the last pointer position on the form: ```js let point = null; form.addEventListener('pointerdown', (e) => { point = { x: e.clientX, y: e.clientY }; }); form.addEventListener('submit', (e) => { e.preventDefault(); distortionWave(form, () => { form.innerHTML = '

You’re in.

'; }, { source: form.querySelector('button'), focus: point, palette: 'aurora' }); point = null; }); ``` ## Theme switch on the whole page Wrap the app in an element (the target can't be `body`), and use `waveOnClick`: it pre-captures the page on hover, so the click starts at once. ```js waveOnClick(themeSwitch, app, () => { const dark = app.dataset.theme !== 'dark'; app.dataset.theme = dark ? 'dark' : 'light'; themeSwitch.setAttribute('aria-checked', dark); }); ``` Keep fixed UI that must not wave (a floating panel, a toast) outside the wrapper: everything inside the target is hidden while the overlay plays. ## Route change in a single-page app Target the outlet, not the whole page; load the data first. ```js nav.addEventListener('click', async (e) => { const link = e.target.closest('a[data-route]'); if (!link) return; e.preventDefault(); const data = await loadRoute(link.dataset.route); // network outside the wave distortionWave(outlet, () => render(outlet, data), { source: link, focus: e, duration: 1400 }); history.pushState({}, '', link.href); }); ``` ## Swapping an image The "after" snapshot waits for the `` inside the target to decode, and the anticipation holds meanwhile. Preload so it doesn't hold: ```js const img = new Image(); img.src = nextSrc; await img.decode(); distortionWave(card, () => { card.querySelector('img').src = nextSrc; }, { source: button, focus: e }); ``` Cross-origin images need CORS (`crossorigin="anonymous"` plus the server header), or they come out transparent in the snapshot. ## Keyboard and focus Nothing special to do for Enter and Space on a real ` ``` ## App-wide settings ```js setWaveDefaults({ duration: 1100, easing: 'ease-out', intensity: 0.7 }); ``` A UI to try settings live (sliders for duration and intensity, easing and palette pickers) is the Options panel of the UI kit. --- # Troubleshooting Find the symptom, check the causes in order. To look at the problem rather than guess, film it with `scripts/film-wave.mjs` and read the frames. First, check the version: `npm ls distortion-wave`. Several visual bugs were fixed recently; anything older than 0.2.1 should be upgraded before you debug. | Fixed in | Bug | |---|---| | 0.1.1 | a rectangle and a glowing rim drawn around elements without background (a row of labels, a transparent grid) | | 0.1.1 | `::before` / `::after` content missing during the wave when a font is loaded from a `data:` URL | | 0.1.1 | password fields empty during the wave (now masked dots, the value is never captured) | | 0.1.2 | square corners when the rounding comes from a parent with `overflow: hidden` | | 0.1.2 | square corners with partial radii such as `border-radius: 12px 12px 0 0` | | 0.2.1 | letters squashed and torn at the start on thin elements (a 26 px row of small text) | ## Nothing animates, the update just happens 1. **No WebGL2.** `warmupWave()` returns `false`. Expected: the update runs without animation. 2. **Reduced motion.** With `prefers-reduced-motion: reduce` you get a 220 ms crossfade, by design. To test the wave, emulate "no preference" in the devtools, or pass `reducedMotion: false` while debugging only. 3. **Target offscreen or 0-size** at the moment of the call. Scroll it into view first, or wave a visible ancestor. 4. **Target is `body` or `html`.** Not supported: wrap the app in a `div` and target that. 5. **4 waves already running.** Only 4 WebGL contexts exist; extra waves update without animation. Wave a common parent once instead of many children at once. 6. **The "after" snapshot took longer than `timeout`** (3 s): usually a slow `update` (network inside it) or an image that never loads. Load data before the call. 7. **The snapshot failed.** The console shows `[distortion-wave] falling back to a plain update:` and the error. A tainted canvas (cross-origin image without CORS) is the usual reason. ## The wave plays, but the new state pops in at the end The DOM was not updated when `update` returned, so both snapshots show the old state. React needs `flushSync`, Vue `nextTick`, Svelte `tick`, Angular `detectChanges`, Lit `updateComplete` (see `frameworks.md`). Also check that the call happens in the event handler, not in an effect that runs after the render. ## The "before" state is already the new one `distortionWave` was called after the state changed: from a `useEffect`, a watcher, or after an `await` that let the framework render. Call it first, and do the state change inside `update`. ## A rectangle, a box or square corners around the element - On a transparent element: upgrade to ≥ 0.1.1. - Rounded parent, square wave: upgrade to ≥ 0.1.2 (the clipping parent needs `overflow` other than `visible`, or `contain: paint`). - Rounded corners from `clip-path` or a mask are not detected. Put the radius on the element itself, or wave the rounded parent. ## Text squashed or wobbly at the very start That is the anticipation: the content is pulled toward the source before the launch. Upgrade to ≥ 0.2.1, where the pull is capped on thin elements. To remove it completely: `pull: 0` (and `inhale: 0` for the ring). ## The effect is too strong for this UI `intensity: 0.4` to `0.7` for dense or text-heavy targets, `particles: false` for a calmer look, `duration` to make it snappier. Tune individual keys (`aberration`, `blur`, `rimStrength`…) only after that. ## Something is missing or wrong in the wave, then fine at the end The snapshot (an SVG `foreignObject` render of the target) could not reproduce it: - Iframes, ``, ``: empty box. - Cross-origin images without CORS: transparent. Add `crossorigin="anonymous"` and the CORS header, or proxy them. - Web fonts not loaded yet, or cross-origin without CORS: fallback font during the wave. Wait for `document.fonts.ready` before the first wave. - Scrolled containers inside the target: shown at scroll 0. - `` pointing outside the target: missing. Inline the symbol. - Closed shadow roots: only the light DOM. - `` and `