@tsparticles/fireworks

tsParticles Fireworks Bundle

tsParticles fireworks bundle to create fireworks effects with a focused API.

Included Packages

• @tsparticles/basic (and all its dependencies)
• @tsparticles/engine
• @tsparticles/plugin-blend
• @tsparticles/plugin-emitters
• @tsparticles/plugin-emitters-shape-square
• @tsparticles/plugin-sounds
• @tsparticles/shape-line
• @tsparticles/updater-destroy
• @tsparticles/updater-life
• @tsparticles/updater-paint
• @tsparticles/updater-rotate

Dependency Graph

flowchart TD

subgraph b [Bundle]
  bf[tsparticles/fireworks]
  bb[tsparticles/basic]
end

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

subgraph p [Plugins]
  pb[tsparticles/plugin-blend]
  pe[tsparticles/plugin-emitters]
  pess[tsparticles/plugin-emitters-shape-square]
  ps[tsparticles/plugin-sounds]
end

subgraph u [Updaters]
  ud[tsparticles/updater-destroy]
  ul[tsparticles/updater-life]
  up[tsparticles/updater-paint]
  ur[tsparticles/updater-rotate]
end

subgraph s [Shapes]
  sl[tsparticles/shape-line]
end

bf --> bb
bf --> ce
bf --> p
bf --> s
bf --> u

Exposed API

The package API is centered on fireworks.

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

// Main API
const instance = await fireworks();
const byId = await fireworks("canvas-id", options);
const byOptions = await fireworks(options);

// Extra helpers
await fireworks.init();
const custom = await fireworks.create(canvas, options);

console.log(fireworks.version);

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

Installation

pnpm add @tsparticles/fireworks

How to use it

ESM / TypeScript

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

const instance = await fireworks({
  colors: ["#ffffff", "#ff0000"],
  sounds: false,
});

instance?.pause();
instance?.play();
instance?.stop();

With explicit canvas id:

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

await fireworks("tsparticles", {
  rate: 3,
  speed: { min: 10, max: 25 },
});

Custom canvas via fireworks.create

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

const canvas = document.getElementById("my-canvas") as HTMLCanvasElement;
await fireworks.create(canvas, { sounds: true });

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 fireworks API, where dependencies must be loaded manually

After loading the bundle, fireworks 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

fireworks();

(async () => {
  const instance = await fireworks();

  instance?.pause();
  instance?.play();
  instance?.stop();
})();

fireworks.create(document.getElementById("custom-id"));

Options

fireworks supports these call signatures:

• fireworks()
• fireworks(options)
• fireworks(id, options)

Main options:

• background String: The background color of the canvas, it can be any valid CSS color, can be transparent as well.
• brightness Number or { min: number; max: number; }: The brightness offset applied to the particles color, from -100 to 100.
• colors String or Array<String>: An array of color strings, in the HEX format... you know, like #bada55.
• gravity Number or { min: number; max: number; }: The gravity applied to the fireworks particles.
• minHeight Number or { min: number; max: number; }: The minimum height for fireworks explosions (the lesser, the higher).
• rate Number or { min: number; max: number; }: The rate of the fireworks explosions.
• saturation Number or { min: number; max: number; }: The saturation offset applied to the particles color, from -100 to 100.
• sounds Boolean: Whether to play sounds or not.
• speed Number or { min: number; max: number; }: The speed of the fireworks particles.
• splitCount Number or { min: number; max: number; }: The number of particles to split the emitter in.

Returned instance methods

The resolved FireworksInstance exposes:

• pause()
• play()
• stop()

Common pitfalls

• Calling fireworks before scripts are loaded in CDN usage
• Assuming tsParticles is exported by @tsparticles/fireworks main entrypoint
• Reusing the same id unintentionally (the package caches instances by id)

Related docs

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