burst-particles

Physics-based particle bursts for the web. Zero dependencies. One function call.

▶ Live Demo · npm · GitHub

import { burst } from 'burst-particles';

button.addEventListener('click', (e) => burst(e, 'party'));

That's it. A canvas is created, animated, and cleaned up automatically.

Installation

npm install burst-particles
# or
pnpm add burst-particles
# or
yarn add burst-particles

Usage

Vanilla JS

import { burst } from 'burst-particles';

document.getElementById('btn').addEventListener('click', (e) => {
  burst(e, 'party');
});

React

import { burst } from 'burst-particles';

function LikeButton() {
  return (
    <button onClick={(e) => burst(e, 'hearts')}>
      ❤️ Like
    </button>
  );
}

Fixed position

burst({ x: window.innerWidth / 2, y: 200 }, 'stars');

Stack multiple effects

const fire = (e) => {
  burst(e, 'stars');
  burst(e, 'gold');
};

Presets

| Preset | Description | |---|---| | party | Multicolored confetti explosion | | fire | Rising embers and flames | | snow | Drifting snowflakes | | hearts | Floating pink hearts | | stars | Spinning golden stars | | bubbles | Soft floating rings | | explode | Fast sharp shrapnel burst | | rain | Falling blue droplets | | gold | Shiny golden coins and stars | | sakura | Gentle cherry blossom petals | | electric | Jagged blue lightning sparks | | neon | Vibrant neon shapes | | flowers | Blooming flower petals | | smoke | Rising grey smoke clouds | | laugh | Flying laughing emojis 😂🤣 |

API

burst(origin, preset?)

| Parameter | Type | Description | |---|---|---| | origin | MouseEvent \| PointerEvent \| { x: number; y: number } | Where the burst spawns | | preset | ParticlePreset \| PresetConfig | Built-in preset name or custom config object |

preset defaults to "party".

Custom Effects

Pass a PresetConfig object to build your own effect from scratch:

import { burst, type PresetConfig } from 'burst-particles';

const goldRain: PresetConfig = {
  count: 60,
  shapes: ['star', 'circle'],
  colors: ['#FFD700', '#FDB931', '#fff'],
  spread: Math.PI * 2,
  speedMin: 3,
  speedMax: 8,
  gravity: 0.2,
  drag: 0.98,
  sizeMin: 6,
  sizeMax: 14,
  lifeMin: 100,
  lifeMax: 180,
  rotates: true,
  fadeOut: true,
  drift: 0.05,
  riseInit: -1,
};

burst(e, goldRain);

Emoji / character particles

Add a chars array to use emojis or text as particles:

burst(e, {
  count: 20,
  shapes: [],
  chars: ['🚀', '⭐', '✨'],
  colors: [],
  spread: Math.PI * 2,
  speedMin: 3, speedMax: 7,
  gravity: 0.2, drag: 0.98,
  sizeMin: 20, sizeMax: 36,
  lifeMin: 80, lifeMax: 130,
  rotates: true, fadeOut: true,
  drift: 0, riseInit: -1,
});

PresetConfig reference

| Property | Type | Description | |---|---|---| | count | number | Number of particles per burst | | shapes | Shape[] | rect circle triangle heart star ring line flower snowflake smoke | | chars | string[] | Emojis or characters to use as particles (optional) | | colors | string[] | Hex colors, chosen randomly per particle | | spread | number | Explosion arc in radians (Math.PI * 2 = full circle) | | spreadDir | number | Direction of the arc in radians (default 0) | | speedMin | number | Minimum launch speed | | speedMax | number | Maximum launch speed | | gravity | number | Downward pull per frame (negative = upward) | | drag | number | Velocity multiplier per frame (0.98 = natural slowdown) | | drift | number | Random horizontal sway per frame | | riseInit | number | Initial upward velocity offset | | sizeMin | number | Minimum particle size in px | | sizeMax | number | Maximum particle size in px | | lifeMin | number | Minimum lifetime in frames | | lifeMax | number | Maximum lifetime in frames | | rotates | boolean | Enable particle rotation | | fadeOut | boolean | Fade out near end of life |

How it works

On first call, a single <canvas> is injected into document.body at z-index: 9999 with pointer-events: none. It resizes with the window. The canvas is shared across all concurrent bursts and the requestAnimationFrame loop stops automatically when all particles have expired — no timers or cleanup needed.

Complex shapes (flower, snowflake, smoke) and emoji characters are pre-rendered to off-screen canvases and cached, so each frame only calls drawImage for them.

License

MIT © K.Prabhasha