distortion∿wave 0.4.0

WebGL2 · zero dependencies · ~17 kB

Wave any element into its next state.

Pass an element and the function that changes it. distortion-wave captures both states and carries the old pixels into the new ones, like startViewTransition() with a material.

LukyVj/distortion-wavenpm i distortion-wave

Checkout

Lagune, live in Paris

Sat 12 Dec · La Cigale · 2 seats

Seats
Balcony B 14–15
Fees
€4.00
Total
€84.00

distortionWave(screen, () => setStep(next), { source: button })

Try it on real controls

Each control runs its change inside distortionWave(). The line under it says which element waves, and where the wave starts.

$10per month

Billed every month. Cancel any time.

Billing period. Waves the price card, from the option you chose.

99.98% uptime this month

Three deploys today, all green. The last one shipped the new checkout to 100% of traffic.

Tabs. Waves the panel only, from the tab. The tab bar stays still.
Like. The button waves itself, from where you pressed it.
Setting. Waves the whole row, since its hint changes too.

How was your delivery?

Pick a star.

Rating. Waves the block, from the star you picked.

Field notebook

A5, dot grid, 120 pages

$18

Add to cart. Waves the card, then focus moves to the new button.
const t = distortionWave(card, update)
await t.finished
Copy. Waves the code, then the label goes back without a wave.

Launch 1 of 3 done

Checklist. Waves the list, since the count in its header changes too.

Arrives ThursdayFree

Delivery. Waves the card, from the radio you picked.

Ticket, early bird

$48 for 2 tickets

Quantity. The + and − buttons wave the card. Typing a number doesn't.

The source sits outside the target: the wave leaves the toolbar and crosses the paragraph.

Alignment. Waves the paragraph only, from the toolbar above it.

0.4.0 Vine and christmas looks, no snap at the end

0.3.0 Eight looks, one file or only what you use

Pages. Waves the list, from the page you picked below it.

Other looks, same wave

An effect keeps the wave's behaviour and changes its look. Each one is its own import: distortion-wave/electric (about 7 kB, with the border), then pixel, glass, burn, ink, halftone, metal, water, vine and christmas (1 to 3 kB each). To switch every demo on this page, pick an effect in the settings below.

Draft

Distortion waves on the web

Electric. The same wave, same timing and lens: the front is a crackling bolt and the outline charges as it passes. effect: electric

Build #218 failed

2 tests failed in checkout.spec.ts.

Pixel. The same wave again: near the front the content breaks into small pixels that flip one by one, and the outline goes out pixel by pixel. effect: pixel

Notifications on

Inbox, 24 unread

Glass. A thick slab of glass trails the front: it bends what's under it, splits it into RGB at its slopes and catches the light. effect: glass

Draft

Q3 plan, rough notes

Burn. The front burns the old content away along a ragged edge: scorch ahead, a white-hot rim, smoke and embers behind. Made for a delete. effect: burn

Proof

Zine #04, cover

Ink. The front bleeds like ink into paper, and around it the content is reprinted in two inks, out of register, risograph style. effect: ink

Issue 12

The weekly, on type

Halftone. Near the front the content turns into a dot screen sized by its tone, and the dots swell with the wave. effect: halftone

Free

Upgrade to Pro

Liquid metal. The front is a rolling bead of liquid chrome that mirrors a studio and, faintly, the content. Best on a dark page. effect: metal

Not backed up

Photos, 1,204 items

Water. Ripples trail the front and refract the content, caustics play on it, and foam breaks on the front. effect: water

Seedling

Garden, week 1

Vine. The front is a band of leaves, leaves fall behind it, a vine grows around the card and the sparks are leaves. effect: vine

Dec 1

24 days to go

Christmas. The front is a candy cane, snow falls behind it, lights go up around the card and snow settles on top. effect: christmas
Electric border, on hover. The electric arcs also make a border that stays on. Three borders, one canvas: every border of the page draws in the same WebGL context.

Tune every wave on this page

Every option of the library, live. They go through setWaveDefaults(), so they apply to every call that doesn't set its own, on this whole page.

Preparing

Order #1042

We're packing your order.

Every change plays the wave here.

setWaveDefaults(null)
// every option at its default: duration from the
// element's size, aurora unless a call sets colours

The page calls this for you: every wave on it, the hero included, runs with these settings.

Effect
Direction
Easing
Colours
Reduced motion

Fine tuning

Lengths are for a 360 × 740 element and scale with the real size. Changed values are marked.

Motion

Speed1×
Distortion1
Number of sparks64

Timing

Inhale before launch0.45s
Travel across2.2s
Edge clears after-0.3s
Edge fade2.8s

Lens

Displacement32px
Lens width140px
Bulge20px
Colour split0.75
Lean to the touch0.9

Blur

Strength18px
At the front6px
Reach ahead90px
Reach behind230px

Colour band

Strength0.9
Length ahead120px
Length behind280px

Edge

Glow strength0.85
Glow width14px
Glow reach320px
Hairline1.5px

Pull

Pull to the source22px
Inhale ring50px

Sparks

Size1.8px
Life2.1s
Reach140px
Spread1

Start with your agent

Pick your framework and paste the prompt into Claude Code, Cursor or any coding agent. It installs the package, points the agent at the docs and adds the skill, so the first wave comes out right.

1

Set it up

Installs the package, points your agent at the docs and adds the skill.

Set up distortion-wave in this Next.js project. It plays a WebGL2 wave on any DOM element when its state changes, with an API shaped like document.startViewTransition().

1. Install the package with this project's package manager: npm i distortion-wave (or the pnpm, yarn or bun equivalent). If a release-age policy (minimumReleaseAge, min-release-age, a registry cooldown…) blocks the install, stop and ask me before changing anything.

2. Add this to AGENTS.md at the project root (create the file if it doesn't exist):

## distortion-wave
Before adding or debugging distortion-wave transitions, follow the distortion-wave skill if it's installed, and read https://distortion-wave.vercel.app/llms.txt. The package docs are in node_modules/distortion-wave/README.md and its types in node_modules/distortion-wave/types/.

3. Install the agent skill: npx skills add LukyVj/distortion-wave --skill distortion-wave
If that command isn't available or fails, copy skill/distortion-wave from https://github.com/LukyVj/distortion-wave into .claude/skills/ instead, or skip this step and tell me.

4. distortion-wave runs in the browser only: call it from a 'use client' component, and wrap the state update in flushSync() from react-dom inside the update callback, so the DOM is current before the second capture.

Don't add any transition yet. When you're done, tell me what you installed and which files you changed.
2

Ask for a first wave

An example to paste next. Swap the pricing card for any control of yours.

Using distortion-wave, make the Monthly / Yearly switch on the pricing card wave the card from one price to the other.

- Wave only the card, not the page.
- The wave should leave from the option I click (source: the button, focus: the click event).
- Keep the switch itself usable: no wave while one is already running on the card.
- Put it in a client component, following the rules in AGENTS.md.

If there's no pricing card, build a small one first: a Monthly / Yearly toggle and a price.

Source, skill and issues on GitHubllms.txt

Or by hand

  1. Add the package

    No dependencies. Works with a bundler or straight from a CDN.

    npm i distortion-wave
  2. Or download one file, with only the looks you use

    The wave is always in. Each look adds 1 to 1.5 kB gzipped (electric about 6 kB), everything is about 25 kB. With a bundler you don't need this: import each look from its own entry and only what you import ships.

    distortion-wave.min.js

    <script src="distortion-wave.min.js"></script>
    <script>
      // the file puts everything on window.DistortionWave
      const { distortionWave } = DistortionWave
    
      button.addEventListener('click', (e) => {
        distortionWave(card, () => {
          card.classList.toggle('done')
        }, { source: button, focus: e })
      })
    </script>
  3. Pass the element and the change

    import { distortionWave } from 'distortion-wave'
    
    button.addEventListener('click', (e) => {
      distortionWave(card, () => {
        card.classList.toggle('done')
      }, { source: button, focus: e })
    })

    The looks ticked above show up in every example from here on. source is where the wave leaves from. focus makes the front lean toward the touch point. Both are optional.

In your framework

The second capture has to see the new DOM, so render before the update returns. Each framework has one line for that.

'use client'
import { useCallback } from 'react'
import { flushSync } from 'react-dom'
import { distortionWave } from 'distortion-wave'

// setState renders later: flushSync makes the DOM current
// before the "after" capture
export function useWave() {
  return useCallback((el, update, options) =>
    distortionWave(el, () => flushSync(update), options), [])
}

// <button onClick={(e) => wave(card.current, () => setPlan('yearly'),
//   { source: e.currentTarget, focus: e })}>

Questions