tsParticles Basic Bundle

tsParticles basic bundle loads the minimum features to a @tsparticles/engine instance for having dots moving in the canvas.

Included Packages

• @tsparticles/engine
• @tsparticles/plugin-move
• @tsparticles/plugin-hex-color
• @tsparticles/plugin-hsl-color
• @tsparticles/plugin-rgb-color
• @tsparticles/plugin-blend
• @tsparticles/shape-circle
• @tsparticles/updater-paint
• @tsparticles/updater-opacity
• @tsparticles/updater-out-modes
• @tsparticles/updater-size

Dependency Graph

flowchart TD

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

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

subgraph p [Plugins]
  pm[tsparticles/plugin-move]
  ph[tsparticles/plugin-hex-color]
  phs[tsparticles/plugin-hsl-color]
  pr[tsparticles/plugin-rgb-color]
  pbl[tsparticles/plugin-blend]
end

subgraph s [Shapes]
  sc[tsparticles/shape-circle]
end

subgraph u [Updaters]
  up[tsparticles/updater-paint]
  uo[tsparticles/updater-opacity]
  uom[tsparticles/updater-out-modes]
  us[tsparticles/updater-size]
end

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

Quick checklist

1. Install @tsparticles/engine (or use the CDN bundle below)
2. Call the package loader function(s) before tsParticles.load(...)
3. Apply the package options in your tsParticles.load(...) config

How to use it

CDN / Vanilla JS / jQuery

The CDN/Vanilla version JS has two different files:

• One is a bundle file with all the scripts included in a single file
• One is a file including just the loadBasic function to load the tsParticles basic preset, all dependencies must be included manually

Bundle

Including the tsparticles.basic.bundle.min.js file will work exactly like v1, you can start using the tsParticles instance in the same way.

This is the easiest usage, since it's a single file with the some of the v1 features.

All new features will be added as external packages, this bundle is recommended for migrating from v1 easily.

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

Once the scripts are loaded you can set up tsParticles like this:

(async () => {
  await loadBasic(tsParticles);

  await tsParticles.load({
    id: "tsparticles",
    options: {
      /* options */
    },
  });
})();

React.js / Preact / Inferno

The syntax for React.js, Preact and Inferno is the same.

This sample uses the class component syntax, but you can use hooks as well (if the library supports it).

Class Components

import React from "react";
import Particles from "react-particles";
import type { Engine } from "@tsparticles/engine";
import { loadBasic } from "@tsparticles/basic";

export class ParticlesContainer extends PureComponent<unknown> {
  // this customizes the component tsParticles installation
  async customInit(engine: Engine) {
    // this adds the bundle to tsParticles
    await loadBasic(engine);
  }

  render() {
    const options = {
      /* custom options */
    };

    return <Particles options={options} init={this.customInit} />;
  }
}

Hooks / Functional Components

import React, { useCallback } from "react";
import Particles from "react-particles";
import type { Engine } from "@tsparticles/engine";
import { loadBasic } from "@tsparticles/basic";

export function ParticlesContainer(props: unknown) {
  // this customizes the component tsParticles installation
  const customInit = useCallback(async (engine: Engine) => {
    // this adds the bundle to tsParticles
    await loadBasic(engine);
  });

  const options = {
    /* custom options */
  };

  return <Particles options={options} init={this.customInit} />;
}

Vue (2.x and 3.x)

The syntax for Vue.js 2.x and 3.x is the same

<Particles id="tsparticles" :particlesInit="particlesInit" :options="options" />

const options = {
    /* custom options */
};

async function particlesInit(engine: Engine) {
    await loadBasic(engine);
}

Angular

<ng-particles [id]="id" [options]="options" [particlesInit]="particlesInit"></ng-particles>

const options = {
  /* custom options */
};

async function particlesInit(engine: Engine): void {
  await loadBasic(engine);
}

Svelte

<Particles
    id="tsparticles"
    options={options}
    particlesInit="{particlesInit}"
/>

let options = {
  /* custom options */
};

let particlesInit = async engine => {
  await loadBasic(engine);
};

Common pitfalls

• Calling tsParticles.load(...) before loadBasic(...)
• Verify required peer packages before enabling advanced options
• Change one option group at a time to isolate regressions quickly

Related docs

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