@lookworld4/micro-interaction-confetti

Task-completion confetti with curated presets on top of canvas-confetti. Use it when a puzzle is solved, a checklist is cleared, or a milestone is reached—without hand-tuning spreads and particle counts.

Features

• Presets tuned for different moments (puzzle-complete, task-done, spark)
• Origin helpers from an element center or pointer clientX / clientY
• prefers-reduced-motion respected by default (canvas-confetti’s disableForReducedMotion)
• Throttle helper for noisy success paths (createThrottledCelebrate)
• TypeScript-first (CelebrateTaskCompleteOptions, ConfettiOptions, presets)
• ESM and CommonJS builds (exports field)

Rendering uses the canvas-based pipeline from canvas-confetti (including its optional worker path when supported), which stays off the DOM layout path and keeps explosions smooth on typical pages.

Installation

npm install @lookworld4/micro-interaction-confetti

pnpm add @lookworld4/micro-interaction-confetti
yarn add @lookworld4/micro-interaction-confetti

canvas-confetti is listed as a dependency so you typically only install this package.

Quick start

Center of the viewport (slightly above center by default):

import { celebrateTaskComplete } from '@lookworld4/micro-interaction-confetti';

await celebrateTaskComplete({ preset: 'puzzle-complete' });

Burst from the last puzzle piece:

import { celebrateFromElement } from '@lookworld4/micro-interaction-confetti';

await celebrateFromElement(document.getElementById('last-tile')!, {
  preset: 'spark',
});

From a click:

import { celebrateFromClientPoint } from '@lookworld4/micro-interaction-confetti';

button.addEventListener('click', (e) => {
  void celebrateFromClientPoint(e.clientX, e.clientY, { preset: 'task-done' });
});

Throttle rapid completions:

import { createThrottledCelebrate } from '@lookworld4/micro-interaction-confetti';

const celebrate = createThrottledCelebrate(1200, { preset: 'puzzle-complete' });
// ...
void celebrate(); // repeats within 1.2s are ignored

Presets

| Preset | Typical use | |------------------|---------------------------------------------------| | puzzle-complete | Default: central burst plus side arcs | | task-done | Two overlapping waves — forms / checklists | | spark | Small, short burst — lightest option |

Pass preset on celebrateTaskComplete or any helper that forwards those options.

Options

Top-level CelebrateTaskCompleteOptions includes:

| Field | Description | |-------|--------------| | preset | puzzle-complete | task-done | spark | | origin | { x, y } in normalized viewport space (0–1) | | respectReducedMotion | Default true; set false only if product explicitly overrides a11y policy | | confetti | Extra fields merged into each internal canvas-confetti call (e.g. zIndex, colors) |

For a custom canvas or global options like useWorker, use createCelebrationInstance (re-exported from canvas-confetti) and pass that instance yourself, or compose with upstream’s API alongside this package.

Clearing animations

import { resetCelebrations } from '@lookworld4/micro-interaction-confetti';

resetCelebrations(); // clears default canvas; see canvas-confetti docs

SSR / non-browser callers are no-ops for fire functions (safe to call from universal code).

Credit

Powered by canvas-confetti: https://www.npmjs.com/package/canvas-confetti

License

MIT