@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 element:

<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

| Prop | Type | Definition | | ------- | ------ | --------------------------------------------------------------- | | id | string | The id of the element. | | loaded | string | The name of a global callback called once particles are loaded. | | options | object | The options of the particles instance. | | url | string | The remote options url, called using an AJAX request |

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