Canvas Confetti: Custom Confetti Bursts with JavaScript

Authorcatdad

Last UpdateOctober 1, 2026

LicenseMIT

Features

Configurable particle count, angle, spread, velocity, gravity, drift, duration, and scale.
Custom colors and normalized launch coordinates.
Square, circle, and star particles.
SVG path, text, and emoji particle shapes.
Full-page default canvas or caller-supplied canvas.
Optional worker rendering for custom canvas instances.
Promise completion, reset control, and reduced-motion handling.

How To Use It

Installation

Load the standalone build in the document:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/confetti.browser.min.js"></script>

Or install the package with NPM:

npm install --save canvas-confetti

The npm package is intended for browser code in a client-side build. It does not run as a Node.js server-side animation API.

const confetti = require('canvas-confetti');

Basic Usage

Call confetti() for the default burst:

<button id="celebrate">Celebrate</button>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/confetti.browser.min.js"></script>
<script>
document.getElementById('celebrate').addEventListener('click', function () {
  confetti();
});
</script>

Customize A Confetti Burst

Pass an options object to change particle count, spread, velocity, origin, colors, and other animation settings.

confetti({
  particleCount: 120,
  spread: 80,
  startVelocity: 35,
  origin: {
    x: 0.5,
    y: 0.7
  },
  colors: [
    '#ff577f',
    '#ff884b',
    '#ffd384',
    '#fff9b0'
  ]
});

Fire From Opposite Sides

angle sets the launch direction in degrees. origin.x and origin.y use normalized page coordinates from 0 to 1.

confetti({
  particleCount: 70,
  angle: 60,
  spread: 55,
  origin: {
    x: 0,
    y: 0.7
  }
});
confetti({
  particleCount: 70,
  angle: 120,
  spread: 55,
  origin: {
    x: 1,
    y: 0.7
  }
});

Use Built-In Particle Shapes

The built-in shapes are square, circle, and star.

confetti({
  particleCount: 100,
  shapes: ['star'],
  scalar: 1.2
});

Squares and circles form the default particle mix. Repeating a shape changes its proportion in the generated particles.

confetti({
  shapes: [
    'circle',
    'circle',
    'star'
  ]
});

Create Emoji Confetti

confetti.shapeFromText() rasterizes Unicode text or emoji into a reusable particle shape. Use the matching scalar value when the shape is created and when it is fired. A different scale can make the rasterized glyph look blurry.

Load a custom web font before calling shapeFromText() when the particle uses that font.

const scalar = 2;
const partyEmoji = confetti.shapeFromText({
  text: '🎉',
  scalar: scalar
});
confetti({
  particleCount: 80,
  shapes: [partyEmoji],
  scalar: scalar
});

Create SVG Path Particles

confetti.shapeFromPath() accepts an SVG path string and returns a reusable particle shape. Path particles are filled and single-color. The browser must implement Path2D.

Every path also needs a transform matrix. The helper can calculate it, but matrix calculation has extra cost. Cache a precomputed matrix when a path will be reused in production, and regenerate that cached matrix after updating Canvas Confetti.

const triangle = confetti.shapeFromPath({
  path: 'M0 10 L5 0 L10 10z'
});
confetti({
  particleCount: 80,
  shapes: [triangle]
});

Use A Custom Canvas

Create one confetti instance for a custom canvas and reuse that function for later bursts. resize: true lets Canvas Confetti update the canvas image dimensions when its displayed size changes.

<canvas id="celebration-canvas"></canvas>

const canvas = document.getElementById('celebration-canvas');
const celebration = confetti.create(canvas, {
  resize: true
});
celebration({
  particleCount: 100,
  spread: 100
});

Render Through A Web Worker

useWorker: true requests worker rendering when the browser can transfer the canvas to a worker. Once transferred, do not access or draw on that canvas from the main thread. Removing the canvas from the DOM is safe.

const canvas = document.getElementById('celebration-canvas');
const celebration = confetti.create(canvas, {
  resize: true,
  useWorker: true
});
celebration({
  particleCount: 150,
  spread: 120
});

Respect Reduced Motion Preferences

Set disableForReducedMotion: true when the animation should be skipped for a visitor whose system reports a reduced-motion preference.

For one burst:

confetti({
  particleCount: 100,
  disableForReducedMotion: true
});

For every burst created by one custom instance:

const celebration = confetti.create(
  document.getElementById('celebration-canvas'),
  {
    resize: true,
    disableForReducedMotion: true
  }
);

Stop An Active Animation

reset() stops the current animation, clears its particles, and immediately resolves outstanding animation promises.

confetti();
setTimeout(function () {
  confetti.reset();
}, 1000);

A function returned by confetti.create() has its own reset() method.

celebration.reset();

Configuration Options

particleCount (Integer, default 50): Number of particles launched by the call.
angle (Number, default 90): Launch angle in degrees. 90 fires upward.
spread (Number, default 45): Angular range around the configured launch angle.
startVelocity (Number, default 45): Initial particle velocity in pixels.
decay (Number, default 0.9): Rate at which particles lose velocity. Values outside 0 to 1 can increase velocity.
gravity (Number, default 1): Downward acceleration applied to particles. Lower values reduce gravity. Negative values move particles upward.
drift (Number, default 0): Horizontal particle drift. Negative values move left and positive values move right.
flat (Boolean, default false): Removes particle tilt and wobble.
ticks (Number, default 200): Number of animation updates before particles expire.
origin (Object): Starting position for the burst.
origin.x (Number, default 0.5): Horizontal origin from 0 at the left edge to 1 at the right edge.
origin.y (Number, default 0.5): Vertical origin from 0 at the top edge to 1 at the bottom edge.
colors (Array<String>): HEX colors used for the particles.
shapes (Array<String|Shape>): Particle shapes. Built-in values are square, circle, and star. Squares and circles form the default mix.
scalar (Number, default 1): Scale applied to each particle.
zIndex (Integer, default 100): Stacking level used by the generated confetti canvas.
disableForReducedMotion (Boolean, default false): Skips confetti when reduced motion is preferred. The returned Promise resolves immediately.

Public API

confetti([options]) → Promise|null

Launches a confetti burst with the supplied options.

When window.Promise exists, the call returns a Promise that resolves after all active confetti animations finish. It returns null when no Promise implementation is available.

Multiple calls made during an active animation reuse the generated canvas and return the active Promise. New particles join the running animation.

confetti.Promise

Assign a custom Promise implementation when required.

const MyPromise = require('some-promise-lib');
const confetti = require('canvas-confetti');
confetti.Promise = MyPromise;

confetti.shapeFromPath({ path, matrix? }) → Shape

Creates a reusable particle shape from an SVG path.

path (String): SVG path data.
matrix: Optional precomputed transform matrix.

The helper fills the SVG path and does not render stroked geometry. Each path uses one particle color and requires Path2D.

confetti.shapeFromText({ text, scalar?, color?, fontFamily? }) → Shape

Rasterizes text or emoji into a reusable particle shape.

text (String): Text or Unicode character to render.
scalar (Number, default 1): Rasterization scale.
color (String, default #000000): Text color.
fontFamily (String, default native emoji): Font used during rasterization, with a sans-serif fallback.

confetti.create(canvas, [globalOptions]) → function

Creates an independent confetti function tied to the supplied canvas. Reuse the returned function rather than creating multiple instances for one canvas.

Global options:

resize (Boolean, default false): Updates the canvas image dimensions when its displayed size changes.
useWorker (Boolean, default false): Requests worker-based rendering when available.
disableForReducedMotion (Boolean, default false): Applies reduced-motion handling to every burst from the instance.

confetti.reset()

Stops the current default-instance animation, clears active particles, and immediately resolves outstanding promises.