@tsparticles/particles

tsParticles Particles Bundle

tsParticles particles bundle to create simple particle effects with a focused API.

Included Packages

• @tsparticles/basic (and all its dependencies)
• @tsparticles/engine
• @tsparticles/plugin-interactivity
• @tsparticles/interaction-particles-collisions
• @tsparticles/interaction-particles-links

Exposed API

The package API is centered on particles.

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

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

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

console.log(particles.version);

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

Installation

pnpm add @tsparticles/particles

Lazy entrypoint (loads dependencies on demand):

import { particles } from "@tsparticles/particles/lazy";

How to use it

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

const instance = await particles({
  count: 120,
  color: "#00f",
  links: true,
  linksColor: "#0ff",
  linksLength: 140,
  radius: 4,
  shape: ["circle", "square"],
});

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

Custom canvas via particles.create

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

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

Options

Main options (shallow overview):

• count Number: particles amount (default: 80)
• radius Number or RangeValue: particle radius (default: 3)
• links Boolean: enable links between particles
• linksLength Number: maximum link distance
• speed Number or RangeValue: particle movement speed
• collisions Boolean: enable particle collisions
• opacity Number: particle opacity
• shape String or Array<String>: particle shape type(s)
• color String: particle color
• linksColor String: link color

Returned instance methods

The resolved ParticlesInstance exposes:

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

Common pitfalls

• Calling particles before scripts are loaded in CDN usage
• Assuming tsParticles is exported by @tsparticles/particles 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/