tsParticles Ribbons Bundle

tsParticles ribbons bundle to create animated ribbons effects with a single API.

Demo website: https://ribbons.js.org

Exposed API

The package API is centered on ribbons.

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

await ribbons(options);
await ribbons("canvas-id", options);

await ribbons.init();
const fireOnCanvas = await ribbons.create(canvas, defaultOptions);
await fireOnCanvas(options);

console.log(ribbons.version);

Installation

pnpm add @tsparticles/ribbons

How to use it

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

await ribbons({
  count: 5,
  positionX: 50,
});

With advanced ribbon shape customization:

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

await ribbons({
  ribbonOptions: {
    count: 70,
    oscillationDistance: {
      min: 120,
      max: 170,
    },
  },
});

Options

Main options:

• count Integer (default: 5)
• ticks Number (default: 200)
• positionX Number (default: 50, in percent)
• position Object (x/y) — deprecated, use positionX instead; y is ignored (emitter always spawns at top-of-canvas)
• emitterSize Object (width/height, default 100/0, in percent) — spawn width is controlled by emitterSize.width (default 100); not always full width
• colors Array<String>
• ribbonOptions Object (particles.shape.options.ribbon)
  • Includes darken: { enable: true, value: 30 } by default
• scalar Number (default: 1)
• zIndex Integer (default: 100)
• disableForReducedMotion Boolean (default: true)

The ribbons bundle disables roll, rotate, tilt, and wobble on ribbon particles by default for better shape stability. The emitter spawns from positionX across a strip whose width is controlled by emitterSize.width (default 100%), with downward movement for a falling-from-top effect. The emitter is always positioned at the top of the canvas.

Deprecated aliases still accepted:

• particleCount (use count)
• position (use positionX)
• origin (use positionX)