@gottheflag/dust

Lightweight, canvas-based particle effects engine for TypeScript.

Dust owns particle simulation (physics, lifetime, pooling). You own how particles look, through a small Renderer interface. Confetti, snow, heart, text/emoji, and images ship as built-in renderers — write your own for anything else.

📖 Full documentation →

Install

npm install @gottheflag/dust

Quick start

import { Dust } from "@gottheflag/dust";
import { ConfettiRenderer } from "@gottheflag/dust/effects";

const dust = new Dust({
	renderer: new ConfettiRenderer(),
});

document.addEventListener("click", (e) => {
	dust.launch({
		origin: { x: e.clientX, y: e.clientY },
		count: 40,
	});
});

That's it — Dust fills the window with a canvas and starts animating on the first launch().

Core concepts

• Dust — one instance per canvas. Owns the simulation loop, the particle pool, and a Renderer. Created once, launch()ed as many times as you like.
• Renderer — a small interface (init?, render, destroy?) that controls how a particle looks. Dust never decides color, shape, rotation, or opacity — that's entirely up to the renderer.
• Particle — the simulation's own shape: position, velocity, gravity, remaining life, and a data field the renderer owns and fully controls.

interface Particle<T = unknown> {
	x: number; y: number;
	vx: number; vy: number;
	gravity: number;
	life: number;
	data: T;
}

interface Renderer<T = unknown> {
	init?(particle: Particle<T>): void;
	render(ctx: CanvasRenderingContext2D, particle: Particle<T>, dt: number): void;
	destroy?(): void;
}

Dust

new Dust({
	root?: HTMLElement,   // defaults to the window
	renderer: Renderer,
	fps?: number,          // caps update/render frequency; physics stays real-time regardless
})

| Method | Description | | ---------------------- | -------------------------------------------------------------------| | launch(options?) | Spawns a burst of particles and starts/continues the simulation. | | on(event, listener) | Subscribe to "start", "update" (per-frame, receives dt), or "end". | | destroy() | Stops the loop, clears particles, tears down the renderer and canvas. |

launch(options)

| Option | Default | Description | | ---------- | --------------------- | ----------------------------------------------------| | count | 30 | Particles to spawn. | | origin | canvas center | Spawn point, { x, y }. | | speed | 4 | Base speed, in px/frame at a 60fps reference rate. | | angle | 0 | Direction in degrees (0 = right, 90 = down). | | spread | 360 | Angular spread, centered on angle. | | gravity | 0.1 | Downward pull per frame. | | duration | 1000 | Lifetime in ms. |

Root & coordinates

Pass root to scope Dust to an element instead of the window — the canvas sizes to that element and tracks its resizes, and default origin is relative to it, not the page.

new Dust({ root: document.querySelector("#hero")!, renderer: new SnowRenderer() });

Built-in effects

import {
	ConfettiRenderer,
	SnowRenderer,
	HeartRenderer,
	TextRenderer,
	ImageRenderer,
} from "@gottheflag/dust/effects";

See src/effects/README.md for each renderer's options, and how to build your own.

Development

npm install
npm run test       # opens the local playground (tests/)
npm run typecheck
npm run build

License

Apache-2.0 — see LICENSE.