← Back to blog

Troubleshooting Common Issues

June 9, 2026 by Matteo Bruni

While tsParticles Ribbons is designed to work out of the box, you may occasionally run into issues depending on your setup. This guide covers the most common problems and their solutions.

Ribbons Not Appearing

If you've added the script and called ribbons() but nothing shows up, check these common causes:

Script Not Loaded

Verify the script is loaded before calling ribbons(). Open your browser's DevTools console and check for errors like ribbons is not defined: 

// Make sure the script is in the <head> or before your code
<script src="https://cdn.jsdelivr.net/npm/@tsparticles/ribbons@latest/tsparticles.ribbons.bundle.min.js"></script>

// Then call ribbons() after the script loads
<script>
  ribbons();
</script>

Missing init() Call

When using the npm package, you must call await ribbons.init() before creating any ribbons: 

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

// This is required!
await ribbons.init();

// Now you can create ribbons
ribbons();

The init() method loads the tsParticles engine and necessary plugins. Without it, the ribbon function has no underlying engine to render with.

Canvas Behind Other Elements

If ribbons are created but hidden behind your content, check the z-index. By default, ribbons render on top of everything. If you need them behind specific elements, set the zIndex option: 

ribbons({
  zIndex: -1, // render behind page content
});

Ensure the parent container has a non-static position (like relative or absolute) for z-index to work correctly.

Ribbons Look Different Than Expected

Colors Are Wrong

tsParticles uses a default color palette when no colors are specified. If your ribbons appear in unexpected colors, you may be seeing the default palette. Override it with your own colors: 

ribbons({
  colors: ['#FF0000', '#00FF00', '#0000FF'],
});

Colors can be any valid CSS value: hex codes, named colors, RGB, HSL, or even CSS custom properties.

Ribbons Are Too Small or Large

The visual size of ribbons depends on your viewport size and the emitter configuration. To make ribbons appear larger, you can adjust the particle size through the underlying tsParticles options: 

ribbons({
  // Adjust the underlying particle configuration
  size: {
    value: 5,
  },
});

Performance Issues

Frame Rate Drops

If ribbons cause your page to stutter, you're likely running too many simultaneous animations. Here's how to diagnose and fix:

  1. Open Chrome DevTools and go to the Performance tab
  2. Record a session while ribbons are active
  3. Look for long frames (red triangles in the frame rate chart)

Common fixes:

// Reduce ribbon count
ribbons({
  count: 12,
});

// Use custom canvas instead of full-screen
const canvas = document.getElementById('my-canvas');
const shoot = await ribbons.create(canvas, { zIndex: 0 });
shoot();

// Limit to one burst at a time
ribbons();

Memory Leaks

If you're creating ribbons in a loop or on repeated events, ensure you're not accumulating canvas elements. The ribbons.create() method returns a reusable function — call it multiple times instead of creating new instances: 

// Bad: Creates a new canvas each time
function onClick() {
  ribbons.create(document.createElement('canvas'));
}

// Good: Reuse the same canvas
const canvas = document.getElementById('my-canvas');
const shoot = await ribbons.create(canvas);

function onClick() {
  shoot(); // Reuses existing canvas
}

Framework-Specific Issues

React: Ribbons Render Twice in Strict Mode

React 18's Strict Mode calls effects twice in development. This can cause duplicate ribbon animations. Wrap your initialization in a ref to prevent double-initialization: 

import { useEffect, useRef } from 'react';
import { ribbons } from '@tsparticles/ribbons';

export function RibbonsEffect() {
  const initialized = useRef(false);

  useEffect(() => {
    if (initialized.current) return;
    initialized.current = true;

    ribbons.init().then(() => ribbons());
  }, []);

  return null;
}

Vue: Ribbons Don't Animate After Navigation

If you're using Vue Router and ribbons stop working after navigating between pages, the canvas may have been removed from the DOM. Re-initialize ribbons in the route's onMounted hook: 

import { onMounted } from 'vue';
import { ribbons } from '@tsparticles/ribbons';

export default {
  setup() {
    onMounted(async () => {
      await ribbons.init();
      ribbons();
    });
  },
};

Getting Help

If you're still experiencing issues after trying the solutions above, here are some resources:

When filing an issue, include your browser version, operating system, and a minimal reproduction (a CodePen or JSFiddle link works great).