react-thanos-effect

Thanos-style dust disintegration for React. Captures children, then dissolves them with WebGL2 instanced particles on an OffscreenCanvas inside a Web Worker. Simulation runs in WebAssembly.

Install

npm install react-thanos-effect

Peer dependencies: react and react-dom ≥ 18.

Usage

import { useRef } from "react";
import ThanosEffect, {
  type EffectTriggerHandle,
  type AnimationMode,
} from "react-thanos-effect";
import "react-thanos-effect/style.css";

function Example() {
  const ref = useRef<EffectTriggerHandle>(null);

  return (
    <>
      <ThanosEffect ref={ref} duration={500} particleSize={2} animationMode="wave">
        <img src="/your-image.png" alt="target" />
      </ThanosEffect>

      <button onClick={() => ref.current?.trigger()}>Snap</button>
    </>
  );
}

Props

| Prop | Default | Description | | --- | --- | --- | | animationMode | "wave" | wave, explosion, spiral, vortex, scatter, rain | | duration | 500 | Animation duration (ms) | | density | 1 | Particle density | | particleSize | 2 | Particle size (px) | | riseFactor | 0.2 | Rise amount (used by wave) | | spawnBandPx | 0 | Spawn lead distance | | useCORS | true | Prefer CORS when embedding images | | backgroundColor | null | Capture background | | className / style | — | Wrapper styles |

Call ref.current.trigger() to start the effect.

Animation modes

import { ANIMATION_MODES, DEFAULT_ANIMATION_MODE } from "react-thanos-effect";

Vite tip

If the worker fails to load in vite dev, exclude the package from prebundling:

// vite.config.ts
export default defineConfig({
  optimizeDeps: {
    exclude: ["react-thanos-effect"],
  },
});

Also import the stylesheet: import "react-thanos-effect/style.css".

Browser support

Requires OffscreenCanvas, Worker, and WebGL2.

Complex children (not a single <img> / <canvas> / <video>) are painted onto a clean canvas so the bitmap can be transferred to the worker. Prefer same-origin or CORS-enabled images in CSS background-image and <img>.

License

MIT