@tsparticles/confetti

tsParticles Confetti Bundle

tsParticles confetti bundle to create confetti effects with a single API.

Included Packages

• @tsparticles/basic (and all its dependencies)
• @tsparticles/engine
• @tsparticles/plugin-emitters
• @tsparticles/plugin-motion
• @tsparticles/shape-cards
• @tsparticles/shape-emoji
• @tsparticles/shape-heart
• @tsparticles/shape-image
• @tsparticles/shape-polygon
• @tsparticles/shape-square
• @tsparticles/shape-star
• @tsparticles/updater-life
• @tsparticles/updater-roll
• @tsparticles/updater-rotate
• @tsparticles/updater-tilt
• @tsparticles/updater-wobble

Dependency Graph

flowchart TD

subgraph b [Bundle]
  bc[tsparticles/confetti]
  bb[tsparticles/basic]
end

subgraph c [Core]
  ce[tsparticles/engine]
end

subgraph p [Plugins]
  pe[tsparticles/plugin-emitters]
  pm[tsparticles/plugin-motion]
end

subgraph s [Shapes]
  sca[tsparticles/shape-cards]
  se[tsparticles/shape-emoji]
  sh[tsparticles/shape-heart]
  si[tsparticles/shape-image]
  sp[tsparticles/shape-polygon]
  ss[tsparticles/shape-square]
  sst[tsparticles/shape-star]
end

subgraph u [Updaters]
  ul[tsparticles/updater-life]
  ur[tsparticles/updater-roll]
  uro[tsparticles/updater-rotate]
  ut[tsparticles/updater-tilt]
  uw[tsparticles/updater-wobble]
end

bc --> bb
bc --> ce
bc --> p
bc --> s
bc --> u

Exposed API

The package API is centered on confetti.

import { confetti } from "@tsparticles/confetti";

// Main API
await confetti(options);
await confetti("canvas-id", options);

// Extra helpers
await confetti.init();
const fireOnCanvas = await confetti.create(canvas, defaultOptions);
await fireOnCanvas(options);

console.log(confetti.version);

@tsparticles/confetti does not expose tsParticles from its main entrypoint. If you need direct engine APIs, import them from @tsparticles/engine.

Installation

pnpm add @tsparticles/confetti

How to use it

ESM / TypeScript

import { confetti } from "@tsparticles/confetti";

await confetti({
  count: 80,
  spread: 60,
  position: { x: 50, y: 50 },
  colors: ["#ffffff", "#ff0000"],
});

With explicit canvas id:

import { confetti } from "@tsparticles/confetti";

await confetti("tsparticles", {
  count: 50,
  angle: 90,
  spread: 45,
});

Custom canvas via confetti.create

import { confetti } from "@tsparticles/confetti";

const canvas = document.getElementById("my-canvas") as HTMLCanvasElement;
const localConfetti = await confetti.create(canvas, { count: 30 });

await localConfetti({ spread: 70 });

CDN / Vanilla JS / jQuery

The CDN/Vanilla JS version has two files:

• One is a bundle file with all the scripts included in a single file
• One includes only the confetti API, where dependencies must be loaded manually

After loading the bundle, confetti is available on globalThis.

Bundle

Use the bundle when you want a single script with all required dependencies.

Not Bundle

This installation requires more work since all dependencies must be included in the page. Some lines above are all specified in the Included Packages section.

Usage

confetti({ count: 60 });

(async () => {
  await confetti({ count: 60, spread: 55 });
})();

confetti("tsparticles", {
  count: 50,
  position: {
    x: 50,
    y: 50,
  },
});

Options

The confetti API accepts:

• confetti(options)
• confetti(id, options)

Main options:

• count Integer (default: 50)
• angle Number (default: 90)
• spread Number (default: 45)
• startVelocity Number (default: 45)
• decay Number (default: 0.9)
• flat Boolean (default: false)
• gravity Number (default: 1)
• drift Number (default: 0)
• ticks Number (default: 200)
• position Object (x/y, default 50/50)
• colors Array<String>
• shapes Array<String>
• shapeOptions Record<string, unknown>
• scalar Number (default: 1)
• zIndex Integer (default: 100)
• disableForReducedMotion Boolean (default: true)

Deprecated aliases still accepted:

• particleCount (use count)
• origin (use position)

Common pitfalls

• Calling confetti before scripts are loaded in CDN usage
• Assuming tsParticles is exported by @tsparticles/confetti main entrypoint
• Passing no first argument in TypeScript (use confetti(options) or confetti(id, options))

Related docs

• All packages catalog: https://github.com/tsparticles/tsparticles
• Main docs: https://particles.js.org/docs/