@tsparticles/astro

@tsparticles/astro

Official tsParticles Astro component

Installation

npm install @tsparticles/astro

or

yarn add @tsparticles/astro

How to use

---
import Particles, { initParticlesEngine } from "@tsparticles/astro";
import { loadSlim } from "@tsparticles/slim";
import type { ISourceOptions } from "@tsparticles/engine";

await initParticlesEngine(async (engine) => {
    await loadSlim(engine);
});

const options: ISourceOptions = {
    background: {
        color: {
            value: "#000"
        }
    },
    fullScreen: {
        zIndex: -1,
    },
    particles: {
        links: {
            enable: true,
        },
        number: {
            value: 100,
        },
        move: {
            enable: true,
        },
    }
};
---

<script>
    import type { Container } from "@tsparticles/engine";

    window.particlesLoaded = function (container: Container) {
        console.log("particlesLoaded callback");
    };
</script>

<Particles id="tsparticles" options={options} loaded="particlesLoaded" />

Dev notes

When running the Astro demo in development, Vite/Astro may serve modules directly from the workspace and the browser needs a browser-ready ESM entry for the wrapper. To ensure the client runtime is initialized before the custom element upgrades, call initParticlesEngine on the client before the element is upgraded.

Recommended minimal pattern (client-side) — place this in your page before the

<script type="importmap">
  {
    "imports": {
      "@tsparticles/astro": "/node_modules/@tsparticles/astro/dist/index.client.js",
      "tsparticles": "/node_modules/tsparticles/esm/index.js"
    }
  }
</script>

<script type="module">
  import { initParticlesEngine } from "@tsparticles/astro";

  // Initialize the engine before the web component upgrades.
  initParticlesEngine(async engine => {
    const { loadFull } = await import("tsparticles");
    await loadFull(engine);
  }).catch(console.error);
</script>

Notes:

• The importmap above is a pragmatic development-time helper so the browser can resolve bare specifiers to the local node_modules dist files. In production builds a bundler or proper package exports should make this unnecessary.
• The important part is that initParticlesEngine is invoked (and begins initialization) before the custom element is defined/upgraded in the page so the component can detect the initialization and not throw.

Props

Reactive updates

The component uses a connectedCallback / attributeChangedCallback pattern to react to attribute changes:

• id change → destroys the current container and reloads particles with the new id.
• options change → destroys the current container and reloads particles with the new options.
• url change → destroys the current container and reloads particles from the new url.
• theme change → applies the theme via loadTheme without a full reload (requires @tsparticles/plugin-themes; safe no-op when the plugin is missing).

On component teardown (disconnectedCallback) the container is destroyed, preventing orphan animations.

particles.json

Find all configuration options here.

You can find sample json configurations here 📖

Demos

Preset demos can be found here

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

Report bugs and issues here

tsParticle Website