react-confetti-engine 🎉

Zero-dependency canvas confetti — physics-based, fully customizable, React-ready.

Install

npm install react-confetti-engine
# or
yarn add react-confetti-engine

Quick start

Imperative (hook)

import Confetti, { useConfetti } from 'react-confetti-engine';

function App() {
  const { ref, burst, cannon, rain, firework, sides, clear } = useConfetti();

  return (
    <div style={{ position: 'relative', height: 500 }}>
      <Confetti ref={ref} />
      <button onClick={() => burst(400, 200)}>🎉 Burst</button>
    </div>
  );
}

Declarative (prop-driven)

<Confetti
  trigger="firework"
  active={showConfetti}
  x={0.5} // 0–1 fraction of canvas width
  y={0.3} // 0–1 fraction of canvas height
/>

Triggers

| Method / trigger prop | Description | | --------------------------- | ----------------------------- | | burst(x, y) | Radial explosion from point | | cannon('left' \| 'right') | Angled spray from screen edge | | sides() | Both cannons at once | | rain() | Curtain fall from top | | firework(x, y) | Starburst pattern + sparks | | fountain(x, y) → stop() | Continuous upward spray | | clear() | Remove all particles |

Config

Pass as config prop or second arg to new ConfettiEngine(canvas, config).

{
  // Physics
  gravity: 0.35,          // downward pull per frame
  drag: 0.984,            // air resistance (0–1)
  wind: 0,                // horizontal push (+right / -left)

  // Particles
  count: 120,             // particles per trigger
  sizeMin: 5,
  sizeMax: 13,
  lifetimeMin: 2800,      // ms
  lifetimeMax: 5000,
  scalar: 1,              // global size multiplier

  // Appearance
  shapes: ['rect', 'circle', 'star', 'triangle', 'ribbon'],
  colors: ['#FF6B6B', '#FFE66D', ...],

  // Velocity
  spread: 80,             // cannon spread angle (degrees)
  startVelocity: 14,      // base speed in px/frame

  // Fade
  fadeEdge: 0.2,          // bottom fraction where alpha fades
  fadeLife: 0.75,         // lifetime fraction when alpha fade starts
}

All config keys can be overridden per-trigger:

burst(x, y, {
  colors: ['#1DB954', '#fff'],
  count: 200,
  shapes: ['star', 'circle'],
});

Vanilla JS

import { ConfettiEngine } from 'react-confetti-engine';

const canvas = document.getElementById('canvas');
const engine = new ConfettiEngine(canvas, { gravity: 0.4 });

engine.burst(canvas.offsetWidth / 2, 200);
engine.firework(400, 150);

// cleanup
engine.destroy();

Component props

| Prop | Type | Default | Description | | --------------- | --------- | ---------------- | --------------------------------------------------------------------------------------------- | | config | object | DEFAULT_CONFIG | Merged with defaults | | trigger | string | — | 'burst' \| 'cannon-left' \| 'cannon-right' \| 'sides' \| 'rain' \| 'firework' \| 'fountain' | | active | boolean | false | Fires trigger on true edge | | x | 0–1 | 0.5 | Horizontal origin fraction | | y | 0–1 | 0.4 | Vertical origin fraction | | triggerConfig | object | {} | Per-trigger config overrides | | className | string | — | Applied to <canvas> | | style | object | — | Inline style for <canvas> |

License

MIT