@tsparticles/angular

Official tsParticles Angular component

Installation

npm install @tsparticles/angular @tsparticles/engine

or

yarn add @tsparticles/angular @tsparticles/engine

How to use

Initialize once

Call NgParticlesService.init(...) once in your app lifecycle before rendering <ngx-particles />.

import { Component, OnInit } from "@angular/core";
import type { Container, ISourceOptions } from "@tsparticles/engine";
import { ClickMode, HoverMode } from "@tsparticles/engine";
import { NgParticlesService } from "@tsparticles/angular";
import { loadSlim } from "@tsparticles/slim";

@Component({
  selector: "app-root",
  templateUrl: "./app.component.html",
})
export class AppComponent implements OnInit {
  id = "tsparticles";

  particlesOptions: ISourceOptions = {
    background: {
      color: {
        value: "#0d47a1",
      },
    },
    fpsLimit: 120,
    interactivity: {
      events: {
        onClick: {
          enable: true,
          mode: ClickMode.push,
        },
        onHover: {
          enable: true,
          mode: HoverMode.repulse,
        },
      },
      modes: {
        push: {
          quantity: 4,
        },
        repulse: {
          distance: 200,
          duration: 0.4,
        },
      },
    },
    particles: {
      links: {
        enable: true,
      },
      move: {
        direction: "none",
        enable: true,
        outModes: {
          default: "out",
        },
      },
      number: {
        value: 80,
      },
    },
  };

  particlesUrl = "https://foo.bar/particles.json";

  constructor(private readonly ngParticlesService: NgParticlesService) {}

  public ngOnInit(): void {
    void this.ngParticlesService.init(async engine => {
      await loadSlim(engine);
    });
  }

  public particlesLoaded(container?: Container): void {
    console.log(container);
  }
}

Template usage

<ngx-particles [id]="id" [options]="particlesOptions" (particlesLoaded)="particlesLoaded($event)"></ngx-particles>

<!-- or -->

<ngx-particles [id]="id" [url]="particlesUrl" (particlesLoaded)="particlesLoaded($event)"></ngx-particles>

Reactive prop changes

The component detects changes to id, options, url, and theme inputs via Angular's OnChanges lifecycle hook:

• id, options, or url change → the existing container is destroyed and particles are reloaded with the new values.
• theme change → loadTheme is called on the current container. This requires the optional @tsparticles/plugin-themes package to be loaded. Without the plugin, theme changes are a safe no-op (no crash, no throw).

The component does not track deep mutations of the options object — it uses reference equality. To trigger a reload, provide a new object reference.

Module setup

import { NgModule } from "@angular/core";
import { NgxParticlesModule } from "@tsparticles/angular";

@NgModule({
  imports: [NgxParticlesModule],
})
export class AppModule {}

Component API

| Input | Type | Default | Description | | --------- | ---------------- | --------------- | ------------------------------------------------------------------------- | | id | string | "tsparticles" | The DOM element id for the particle container. Change triggers reload. | | options | ISourceOptions | — | The particle configuration object. Change triggers reload. | | url | string | — | A URL to a JSON particle config. Change triggers reload. | | theme | string | — | Theme name (requires @tsparticles/plugin-themes). Safe no-op otherwise. |

| Output | Type | Description | | ----------------- | -------------------------------------- | ------------------------------------------------------------- | | particlesLoaded | EventEmitter<Container \| undefined> | Emitted after tsParticles.load resolves with the container. |

Cleanup

When the component is destroyed (ngOnDestroy), the particle container is automatically destroyed — no orphan animations remain.

Theme support

The theme input prop requires the optional @tsparticles/plugin-themes package to be installed and registered during NgParticlesService.init(...). Without the plugin, theme changes are silently ignored.

Demos

The demo website is here

https://particles.js.org

There's also a CodePen collection actively maintained and updated here

https://codepen.io/collection/DPOage