Custom Confetti Bursts in JavaScript – js-confetti

js-confetti is a standalone JavaScript library for creating canvas-based confetti effects in HTML.

It renders colored particles or emoji and can fire a burst from the screen edges or a specific pointer position, with controls for particle count, size, and colors.

js-confetti is a standalone JavaScript library for creating canvas-based confetti effects in the browser.

It renders colored particles or emoji and can fire a burst from the screen edges or a specific pointer position, with controls for particle count, size, and colors.

Features

• Browser build and ES module.
• TypeScript declarations included.
• Optional custom canvas element.
• Promise returned when each confetti batch finishes.
• Animation speed adjusts according to canvas width.

How to Use js-confetti

Installation

Load the standalone build from a CDN:

<script src="https://cdn.jsdelivr.net/npm/js-confetti/dist/js-confetti.browser.js"></script>

Or install the package from npm:

npm install js-confetti

Then import the class:

import JSConfetti from 'js-confetti';

Basic Usage

Create a JSConfetti instance and reuse it for later effects. The default instance creates a canvas that fills the viewport with position: fixed, uses a z-index of 1000, and ignores pointer input.

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

Use Emoji As Confetti

Pass an emojis array to render emoji characters:

jsConfetti.addConfetti({
  emojis: ['🎉', '✨', '🥳', '🎈'],
  emojiSize: 70,
  confettiNumber: 40
});

Customize Colors, Size, And Quantity

Set the particle palette, radius, and quantity for standard confetti:

jsConfetti.addConfetti({
  confettiColors: [
    '#ffbe0b',
    '#fb5607',
    '#ff006e',
    '#8338ec',
    '#3a86ff'
  ],
  confettiRadius: 8,
  confettiNumber: 180
});

Trigger Confetti From A Click Position

addConfettiAtPosition() requires coordinates through confettiDispatchPosition. Pointer and mouse events expose suitable viewport coordinates through clientX and clientY.

document.addEventListener('click', function (event) {
  jsConfetti.addConfettiAtPosition({
    confettiDispatchPosition: {
      x: event.clientX,
      y: event.clientY
    },
    confettiNumber: 80,
    confettiRadius: 5
  });
});

Use A Custom Canvas

Pass an existing HTMLCanvasElement when the effect needs a canvas controlled by your page:

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

const canvas = document.getElementById('celebration-canvas');
const jsConfetti = new JSConfetti({
  canvas: canvas
});
jsConfetti.addConfetti();

Run Code After The Animation Finishes

Both confetti methods return a Promise<void> for the batch they create:

await jsConfetti.addConfetti({
  confettiNumber: 120
});
console.log('Animation complete');

Promise chaining works as well:

jsConfetti.addConfetti().then(function () {
  console.log('Animation complete');
});

Constructor Option

• canvas (HTMLCanvasElement): Uses an existing canvas element. When omitted, js-confetti creates a fixed full-screen canvas inside document.body.

const jsConfetti = new JSConfetti({
  canvas: document.getElementById('celebration-canvas')
});

Confetti Options

These options apply to addConfetti() and addConfettiAtPosition():

• confettiRadius (number, default 6): Sets the radius of standard confetti particles.
• confettiNumber (number, default 250): Sets the particle count. The default becomes 40 when an emojis array is passed.
• confettiColors (string[]): Sets the colors for standard particles. The defaults are #fcf403, #62fc03, #f4fc03, #03e7fc, #03fca5, #a503fc, #fc03ad, and #fc03c2.
• emojis (string[], default []): Uses characters from the array as emoji confetti.
• emojiSize (number, default 80): Sets the rendered emoji size.

addConfettiAtPosition() uses one additional option:

• confettiDispatchPosition ({ x: number, y: number }): Sets the coordinates where the burst begins. Pass this option when calling addConfettiAtPosition().

API Methods

addConfetti()

Launches a confetti batch from both sides of the canvas and returns a Promise<void>.

jsConfetti.addConfetti(options);

addConfettiAtPosition()

Launches a batch from the coordinates in confettiDispatchPosition and returns a Promise<void>.

jsConfetti.addConfettiAtPosition({
  confettiDispatchPosition: {
    x: 300,
    y: 200
  }
});

clearCanvas()

Drops the active confetti batches from the instance:

jsConfetti.clearCanvas();

destroyCanvas()

Removes the instance’s canvas element from the DOM. This also removes a custom canvas supplied through the constructor.

jsConfetti.destroyCanvas();

Alternatives & Related Resources

• Add Canvas Confetti Effects to Any Website with Vanilla Confetti
• Simple Celebrate Confetti Animation In JavaScript – Party.js
• Confetti Falling Animation In Pure JavaScript – confetti.js
• Create Celebration Fireworks/Confetti Animations With DOM-Particles Library
• Confetti Falling Animation In Pure CSS