Make yoursMake yours
go woooom.woooom.

Quick start

$ npm i woooms

import { Woom } from "@woooms/react";

  <Woom variant="jelly">
    <button>Buy now</button>
  </Woom>

Pictures too: woooms/shapes makes any cut-out picture of something, a balloon, a gummy, a gold statue of it. See Pictures.

Variants

Start here

A dozen to try first, from every corner of the catalogue.

Everyday

For the jobs every site has: holding to confirm, sending, copying, buying, deleting, uploading.

In the core

Part of the renderer itself: nothing more to download.

With sound on, the keycap clacks on the way down and, more softly, on the way back. The sound is synthesised with Web Audio, so there's nothing to download, and the audio context is only created from a real press, never on load. Keyboard users get a CSS press (:focus-visible:active) instead, so the focus ring stays on screen.

<Woom variant="keycap" sound>
    <button>Enter</button>
  </Woom>

Classics

The four that started it.

Games

Nods to the games everyone has played.

Screens and pixels

Old machines and the way they drew.

Mechanisms

Things that open, lift, swing and fly.

Surfaces

What it's made of, and how the light plays on it.

A coin with a real state

While it shows a state it stays out even if the pointer leaves. aria-busy is also what screen readers hear, so the state is never only in the effect.

<Woom variant="coin" kind="spin">
    <button onClick={pay} aria-busy={paying} data-woom-state={paid ? "done" : undefined}>
      {paying ? "Paying…" : paid ? "Paid" : "Pay now"}
    </button>
  </Woom>

Not just buttons

This page is a studio too. Type a word anywhere, drop a photo or paste your website's address, and it comes out onto the page in 3D. Drag a card onto it to make it of that, or into the bin to throw it away.

On a wide screen, with motion allowed, this page is a studio too: type a word anywhere, drop a photo or paste your website's address, and it comes out onto the page in 3D, to be made of any of the variants above.

Controls

The toggle variant is for controls that latch: switches, checkboxes, tabs and radios rise on hover, clack down when pressed and stay sunk in while on, with a switch's knob and a checkbox's tick drawn in 3D. A slider is a long switch whose knob follows the value as you drag it, ticking as it goes. The React package comes with them ready-made: Switch, Checkbox, RadioGroup, Segmented, Tabs, ToggleButton, Chip, Accordion, Slider, RangeSlider, Stepper, Rating, OptionCards, SplitButton, Pagination and Swatches, with their stylesheet.

import { Checkbox, Segmented, Slider, Switch } from "@woooms/react/controls";
  import "woooms/controls.css";

  <Switch label="Sound" checked={sound} onCheckedChange={setSound} />
  <Slider label="Volume" value={volume} onValueChange={setVolume} />
  <Checkbox defaultChecked>Speed lines</Checkbox>
  <Segmented
    legend="Size"
    options={[{ value: "sm", label: "SM" }, { value: "md", label: "MD" }]}
    value={size}
    onValueChange={setSize}
  />

Each works controlled or not. Keep their sizes as they are: the shader draws the knob and the tick at the same geometry as the CSS.

Bursts

Any variant can throw something when it's pressed: confetti, sparks, hearts or bubbles, in real 3D, out of the spot you pressed and away down the page. It also goes off when the button becomes done (data-woom-state="done"), from its middle. Press again and again and each press throws its own volley while the others finish their fall; the button stays out till the last piece is gone. With sound on, each has its own.

import { Woom } from "@woooms/react";

  <Woom variant="pop" burst="hearts">
    <button>Like</button>
  </Woom>

Like the variants, each works by name, and its code is only fetched once a button that uses it is hovered. Visitors who ask for reduced motion get no 3D at all, so no bursts either.

Your own variant

Every variant is written against the same plugin API, and yours can be too, registered under a name of its own (or one of theirs, to put yours in its place). A variant is a plain object: its default options, springs, a pose function (how far the block lifts, leans and tilts for a given pop, press and pointer), and optionally its own per-button physics, GLSL hooks to bend or shade the block, and a sound.

import { defineVariant, registerVariant } from "woooms";

  const float = defineVariant("float", {
    defaults: { depth: 0.3, lean: 0.1, tilt: 0.25, taper: 0, lines: false, sound: false },
    springs: {
      pop: { stiffness: 120, damping: 14 },
      pressDown: { stiffness: 600, damping: 30 },
      pressUp: { stiffness: 600, damping: 30 },
      tilt: { stiffness: 80, damping: 12 },
    },
    pose: ({ pop, press, tiltX, tiltY, height, options }) => ({
      y: height * 0.2 * pop,
      z: height * 0.8 * pop * (1 - 0.5 * press),
      rotX: (-options.lean + options.tilt * tiltX) * pop,
      rotY: options.tilt * tiltY * pop,
      rotZ: 0,
      scaleZ: Math.max(0.001, pop),
      taper: 0,
      dish: 0,
    }),
    wallShade: 0.4,
    bevel: (h) => h * 0.08,
    bottomOut: false,
    lineSpeed: 0,
  });

  registerVariant("float", float);

The pose must be flat (all zeros) at pop: 0, so the 3D twin matches your button exactly when it appears and disappears. GLSL hooks are documented on the VariantDef type.

Pictures, made of things

Any picture can come out in 3D too, made of something: a cut-out photo, a logo, an icon, an emoji. Its outline is read from its transparency, so it comes out as its own shape, blown up off the page, and the picture turns into its material: a balloon of it, a gummy of it, a gold statue of it. Each is played with as its material is.

Holographic foil over the print, the rainbow sliding as you move.

Material

BalloonGummyClayChocolateWaxIceChromeGoldMarbleHoloCut outThermalOne-bitHalftoneStart over

import { Shape } from "@woooms/react/shapes";

  <Shape material="balloon" src="/me.png" alt="Me" height={200} />

Materials

Fourteen, each the Studio's own. Some turn the picture into themselves (a statue, a gummy in your colour), some lay themselves over it (foil, a print); each is lit by a lamp that follows the pointer.

Picture options

As options to shape() and props of <Shape>, or as data-woom-* attributes on the picture for autoShapes().

shape() returns a function that undoes it; calling it again for the same picture starts it over. The <img> stays yours: its alt text, its clicks, its layout.

Moments: a paper dart

woooms/fx is for the moments an interface has: something sent, something done. One call, and the element itself, as it is on the page, is folded into a paper dart, crease by crease, and thrown: off the page, or into another element. Press Send.

import { fly } from "woooms/fx";

  function Draft() {
    const outbox = useRef<HTMLDivElement>(null);
    return (
      <>
        <form onSubmit={(e) => {
          e.preventDefault();
          fly(e.currentTarget, { to: outbox.current!, back: true });
        }}>…</form>
        <div ref={outbox}>Outbox</div>
      </>
    );
  }

Landing

land() is fly() the other way: a paper dart folded from the element glides in from off the page, banking into its curve, flares and touches down where the element is, turns to lie as it does, and unfolds into it, crease by crease. For whatever's new: a message, a notification, a row that's just come in.

import { land } from "woooms/fx";

  // Before it's painted, so it's never seen there till the dart has landed.
  useLayoutEffect(() => {
    land(newest.current!, { sound: true });
  }, [messages.length]);

Printer

print() brings the element in printed: a receipt printer pops up where its bottom edge is and prints it, the paper coming up out of the slot top edge first, a line at a time, the ink coming up on it as it passes the head, curling towards you as receipt paper does. Then it's cut with a little tug, settles flat into its place, and the printer goes. For receipts, tickets, anything that's just been made for you.

import { print } from "woooms/fx";

  // Mounted out of sight; printed in as it's shown.
  useLayoutEffect(() => {
    print(receipt.current!, { sound: true });
  }, []);

Scratch card

scratch() covers the element in a scratch card's coating, wiped on with a glint: matte silver latex, stars printed on it, glitter in it that catches the light as the pointer moves. Wherever the pointer goes the coating comes away, its edge crumbly, leaving crumbs of latex lying about as a coin does; once enough's off (reveal, half and a bit by default), the rest wears away and it resolves. Pick the coating's colour with foil. Without 3D, it's a canvas you rub off, with a finger too.

import { scratch } from "woooms/fx";

  useEffect(() => {
    scratch(card.current!, { sound: true }).then(() => claim(prize));
  }, [prize]);

Rolled up

roll() rolls the element up as a poster on a table is: from an edge (from, the bottom by default) it lifts and rolls up on itself round a spiral, picture in, the paper's back on the outside, then the roll carries on rolling, off the page. unroll() is the same backwards: a roll comes rolling in and lays the element out flat.

import { roll, unroll } from "woooms/fx";

  <button onClick={async () => {
    await roll(poster.current!, { sound: true });
    archive(poster.id);
  }}>Archive</button>

Page turn

turn() turns the element over like the page of a book: hinged along one edge, it's lifted by the other (from, the right by default), its corner first, and turns over through the air, bowed as a page is, to lie down on the other side, its back up, and fade away; what's under it shows as it goes. For steps, onboarding, a gallery.

import { turn } from "woooms/fx";

  <button onClick={async () => {
    await turn(steps.current[at]!, { sound: true });
    setAt(at + 1);
  }}>Next</button>

Flip

flip() turns an element over like a card to show another: lifted and turned, faster and faster, till it's edge on, where the other side (an element laid out in the same place, hidden till then) takes over, turning on from edge on and set down with a little bounce. Its edge shows as it turns; its shadow goes with it. Without a back, it's turned right round to itself.

import { flip } from "woooms/fx";

  <div style={{ position: "relative" }} onClick={() => flip(question.current!, answer.current!)}>
    <div ref={question}>What's the capital of Australia?</div>
    <div ref={answer} style={{ position: "absolute", inset: 0, visibility: "hidden" }}>
      Canberra.
    </div>
  </div>

Origami

origami() folds the element into a model, a step at a time, as hands would: squared up first (whatever's past a square folded behind it), then folded, creased and shaped. A crane flaps its wings and flies away; a frog crouches, hops, and leaps off head over heels; a boat sails away, rocking; a fortune teller chomps three times and spins off. model says which, and to sends it into something.

import { origami } from "woooms/fx";

  <button onClick={() => origami(note.current!, { model: "crane" })}>Fold it</button>

Crumpled paper

crumple() crushes the element into a ball of paper in two hands. It's simulated: a sheet that bends but never stretches, so it creases where it gives, with the element still printed on it, folded up in the ball. Then it's lobbed into the bin, or let go of, to bounce and roll off the page. Tick a note off.

import { crumple } from "woooms/fx";

  function Note({ text, onDone }: { text: string; onDone: () => void }) {
    return (
      <li>
        {text}
        <button onClick={async (e) => {
          await crumple(e.currentTarget.closest("li")!, { to: document.querySelector("#bin")! });
          onDone(); // gone: take it out of the list
        }}>Done</button>
      </li>
    );
  }

Sticker

peel() peels the element off the page like a sticker: a corner lifted, then the line where it's still stuck drawn across it, the peeled part rolled back over itself, its white back up, the glue giving in fits and starts. What's under it on the page shows as it comes away. Free, it's pulled off the page, or turned face up and stuck onto another element.

import { peel } from "woooms/fx";

  <div className="coupon">
    <code>WOOOMS20</code>
    {/* Over the code: peeled off, the code shows. */}
    <button className="sticker" onClick={(e) => peel(e.currentTarget)}>Peel me</button>
  </div>

Torn in two

tear() tears the element in two, from its top edge down along a ragged line: the halves open from the tear as it runs, one edge showing the paper's white core with its fibres sticking out. Let go of, they fall off the page, turning over as they go; or, given to, they're tossed into it.

import { tear } from "woooms/fx";

  <button onClick={async () => {
    await tear(ticket.current!, { sound: true });
    cancel(order.id);
  }}>Cancel ticket</button>

Shredder

shred() feeds the element through a shredder that pops up under it: it takes hold with a jolt, the motor hums and grinds, and the element comes out of the bottom in strips, still printed, curling as cut strips do; once it's all through they drop away and the shredder goes.

import { shred } from "woooms/fx";

  <button onClick={async () => {
    await shred(statement.current!, { sound: true });
    remove(statement.id);
  }}>Shred it</button>

Fire

burn() sets the element alight: a spark at its bottom edge, a little flame, and then it catches. A ragged front climbs it, faster up than across as fire does: ahead of it the paper browns, at it a line glows and flickers, flames lick up off it, and behind it the paper chars black, curls and falls away to ash that drifts up with the smoke. What's under it on the page shows through the hole. Give it at, a point or the click, and it's lit there: click anywhere on the note.

import { burn } from "woooms/fx";

  <button onClick={async () => {
    await burn(message.current!, { sound: true });
    onDelete(); // gone for good
  }}>Burn after reading</button>

Dust

dust() turns the element to dust: it trembles, then a ragged front sweeps across it and, wherever it's passed, the element comes apart into thousands of specks of itself that the wind carries off, eddying and turning to ash. wind says which way it blows, "left" or "right".

import { dust } from "woooms/fx";

  <button onClick={async () => {
    await dust(card.current!, { sound: true });
    removeMember(member.id);
  }}>Remove from team</button>

Vortex

vortex() whirls the element away. It twists, its middle turning faster than its edge, then comes apart into specks of itself: down a drain (a hole opens in its middle and the rest pours into it, winding into spiral arms, or into to), or, with kind: "tornado", up a column that widens as they climb.

import { vortex } from "woooms/fx";

  <button onClick={() => vortex(files.current!)}>Clear it out</button>

Unravelled

unravel() knits the element, its picture worked in stitches, then pulls its yarn from the top: it comes undone a row at a time, along one and back along the next, as knitting does, the yarn going off up the page crimped and in the colours of the stitches it was, till its tail whips away. to pulls it into something.

import { unravel } from "woooms/fx";

  <button onClick={() => unravel(sale.current!)}>End the sale</button>

Shattered glass

shatter() breaks the element like a pane of glass, where it's hit: cracks race out from the blow, radial and in rings, and the picture goes askew from shard to shard; a beat, then the shards fall out, nearest the blow first, tumbling off the page and flashing as they turn, splinters spraying. Pass the click as at and it breaks where it was clicked; for a see-through pane, pass clear and its shards are as clear as it was.

import { shatter } from "woooms/fx";

  <div ref={pane} onClick={async (event) => {
    await shatter(pane.current!, { at: event, sound: true });
    setBroken(true);
  }}>The glass ceiling</div>

Genie

genie() sucks the element into another, as a window's minimised into the dock: its near edge is drawn out to it, the element stretched behind it in a funnel that curves into it, then the rest pours down after, slowly and then all at once, and it's gone in, which catches it with a little dip. For whatever's added to a cart (a product's photo, say), saved to a folder or put away.

import { genie } from "woooms/fx";

  <button onClick={async () => {
    await genie(product.current!, { to: cart.current!, back: true, sound: true });
    addToCart(item);
  }}>Add to cart</button>

Melt

melt() melts the element away: it goes soft and sags, then melts down, its top sagging in lobes, into a pool along its bottom edge that spreads out either side, drips running off it; then what's left lets go and runs on down the page after them, thinning away as it goes. Its own picture runs with it, text and all. For whatever's run out: an offer that's over, a deadline that's passed.

import { melt } from "woooms/fx";

  useEffect(() => {
    if (expired) melt(offer.current!, { sound: true }).then(onGone);
  }, [expired]);

Ice

freeze() ices the element over, and keeps it so: frost creeps in from its edges in ferns, the ice thickens over it, and it's seen through the ice, cold and a little bent, out of reach (no pointer, aria-disabled) till thaw(), when the ice goes wet, drops run down it and it melts away. kind: "block" sets it in a deep block of ice instead, turned a little to show it. For whatever's paused, locked or on hold: a frozen card, a paused plan.

import { freeze, thaw } from "woooms/fx";

  useEffect(() => {
    const card = ref.current!;
    if (frozen) freeze(card, { sound: true });
    else thaw(card);
  }, [frozen]);

Moment options

fly(), crumple(), peel(), tear(), shred(), burn(), dust(), shatter(), genie() and melt() each return a promise that resolves once it's gone (or, with back, once it's back), the element left hidden for you to remove. Called again while it's going, it's the same moment.

The paper is cut from the element's own picture, so it's your button, your card, your draft that's folded, crumpled, peeled, torn, shredded, burnt, broken, sucked away or melted; the paper's back is its background colour. woooms/fx is 6 KB; each moment's own code (1.4 to 6 KB) is fetched the first time it's played, or ahead with prepare(). shred() and melt() take only back and sound; shatter() and burn() take at too, a point or the click that broke it or lit it; dust() takes wind, "left" or "right"; vortex() takes kind and to; origami(), model and to. freeze() keeps it so: it resolves once it's frozen through, and thaw() once it's melted away.

Options

Precedence, lowest to highest: defaults, then CSS variables, then data-woom-* attributes, then JavaScript options.

Theming

CSS variables are read from the button's computed style each time it's hovered, so they follow your themes, dark mode and media queries. Any colour the browser understands works: color-mix(), oklch(), var(), named colours. woooms lets the browser paint the colour into a 1×1 canvas and reads the pixel back, rather than parsing CSS itself.

Page-wide settings

import { configure, preload, isSupported, stats } from "woooms";

  configure({
    zIndex: 40,             // overlay canvas base z-index
    reducedMotion: "user",  // "user" | "always" | "never"
    maxDpr: 2,              // device pixel ratio cap
    shadowStrength: 1,      // how dark every shadow is; 0 for none
    shadowSoftness: 1,      // how soft their edges are; 2 is twice the blur
    shadowLength: 1,        // how far they fall, as if the light were lower
    shadowGrain: 0,         // a film grain in them, 0 to 1
  });

  preload();       // fetch the renderer now (e.g. on idle) instead of on first hover
  isSupported();   // true when this visitor gets the WebGL effect
  stats();         // debug counters: loaded, live blocks, average frame cost

Accessibility

• The effect is decoration only. Nothing it shows carries meaning that the button itself doesn't.
• The canvas is aria-hidden and pointer-events: none. Clicks, taps and keys always reach your element.
• A button showing a keyboard focus ring (:focus-visible) never pops, so the ring is never hidden. The fallback stylesheet gives focused buttons a small 2px lift instead.
• disabled and aria-disabled="true" buttons are left alone.
• Reduced motion is honoured by default, both by the WebGL layer and by the CSS fallback.

Support & fallbacks

The WebGL effect needs WebGL2, a mouse (hover: hover and pointer: fine) and motion allowed. Everything else degrades:

While WebGL is in charge, html has a data-woom3d attribute; the fallback CSS stays out of the way. A popped-out button has data-woom-live; a button handed back to CSS has data-woom-fallback.

Layering (z-index)

The overlay canvas is fixed over the viewport with z-index: 40 by default: above ordinary content and sticky headers, below typical modals and toasts. When the hovered button sits in a stacking context with a higher z-index (a drawer at 1000, say), the canvas is raised just above it for as long as that button is out. Buttons in the browser's top layer (modal dialogs, popovers, fullscreen) sit above any z-index, so while one is out the canvas joins the top layer too, as a popover, and leaves it once nothing there is out. In browsers without popovers those buttons use the CSS fallback.

How it works

1. On page load you pay for a few delegated listeners and every variant's name: 3 KB gzipped. No canvas, no WebGL context.
2. The first mouse over the page, once the browser is idle, or the first hover on a woooms button, fetches the renderer (about 20 KB gzipped) and its variant, unless it's pop or keycap (1–4.5 KB), waits for document.fonts.ready and creates one shared canvas.
3. The button is measured and painted into a texture: background, every text run at its laid-out position, inline SVGs with their computed styles, images it may read (as object-fit places them). A rounded-rectangle block matching its border-radius is extruded behind it.
4. Springs (semi-implicit Euler) drive pop, press and pointer follow. The DOM button goes to opacity 0 while its twin is out and is stretched with a CSS transform over the block's footprint, so clicking anywhere on what you see clicks your real element; layout never moves. The shadow is the block's own rounded shape, cast away from the light and softening as the block rises. The frame loop runs only while something moves, and the canvas is hidden when idle.
5. The block is rebuilt when the button's size, markup, colours, font or theme variables change, even mid-hover. It's freed as soon as it settles back or the element leaves the DOM.

Why not three.js? The same effect built on three.js weighs 143 KB gzipped. The scene is one extruded shape, one textured face, one lit wall shader and a soft shadow, so a purpose-built WebGL2 renderer does it, both variants included, in about a tenth of the size.

Known limits

• The face copies background colours and gradients (linear, radial, conic), borders, inset rings, text, inline SVG and images from the same site or served with CORS. Background images, text shadows, outer box-shadows and other sites' images aren't painted; a gradient it can't follow (a calc() position, say) is left out and the colour shows.
• Inline SVG icons are painted through data: URLs: a Content-Security-Policy whose img-src leaves out data: drops them from the face.
• An inline element broken over two lines (a long link) has no one box to lift, and keeps its CSS fallback. So do elements inside a rotated ancestor, and vertical writing modes aren't laid out.
• Buttons with a transparent background get a solid face in the wall colour (glass and jelly draw see-through).
• Content inside other components' shadow roots isn't painted onto the face; elements that are themselves in a shadow root work.
• The block is drawn over everything below the canvas's z-index, including content that scrolls over the button (a sticky header, say) while it's out.
• While it's out, the block takes the clicks for whatever it covers, just as it hides it. Once it settles back, everything underneath is reachable again.

Free, all of it

Every variant is free and MIT. If woooms made your page a little more fun, you can keep it going.