ParticleFirework.js

ParticleFirework.js is a lightweight JavaScript class that enables you to create customizable particle effects, perfect for adding flair to your web projects. Control the duration, delay, number of particles, colors, size, shape, and spread to achieve the perfect visual effect.

Download

Installation

To use ParticleFirework.js, simply include the script in your HTML file or import it into your JavaScript project.

Via Script Tag

<script src="path/to/ParticleFirework.js"></script>

Via Module Import

import ParticleFirework from 'path/to/ParticleFirework.js';

Usage

Instantiate a new ParticleFirework object with customizable options to trigger a particle effect from the center of a specified HTML element.

Basic Example

new ParticleFirework({
  elementId: 'myElement',
  duration: 200,
  delay: 500,
  numParticles: 150,
  colors: ['#ff6b6b', '#ff9f6b', '#ffcd6b', '#cdff6b', '#6bff9f', '#6bcfff', '#6b9fff'],
  size: 5,
  shape: 'circle',
  spread: 3
});

HTML Setup

<div id="myElement"></div>

Configuration Options

When creating a new ParticleFirework, you can pass an options object to customize the behavior and appearance of the particles.

Options

elementId: string, The ID of the HTML element from which particles will originate.
duration: number, Default 100, The duration over which particles are generated, measured in animation frames.
delay: number, Default 0, Delay before the animation starts, in milliseconds.
numParticles: number, Default 100, Total number of particles to create during the animation.
colors: array, Default ['#6bff9f'], An array of color strings to use for the particles. Colors will be chosen randomly from this array.
size: number, Default 5, The size of each particle, in pixels.
shape: string, Default 'circle', The shape of the particles. Supported values are 'circle', 'square', and 'triangle'.
spread: number, Default 2, Controls the spread (velocity) of particles. Higher values result in a wider spread of particles.

Triggering the Particle Effect

The ParticleFirework class provides a trigger() method that allows you to manually start the particle effect at any time. This method can be called on an instance of ParticleFirework, and it will initiate the particle animation based on the options you specified during instantiation.

Example Usage

// Create an instance of ParticleFirework
const firework = new ParticleFirework({
  elementId: 'myElement',
  duration: 150,
  numParticles: 200,
  colors: ['#ff6b6b', '#ff9f6b', '#ffcd6b', '#cdff6b', '#6bff9f', '#6bcfff', '#6b9fff'],
  size: 5,
  shape: 'circle',
  spread: 3
});

// Manually trigger the firework effect
firework.trigger();

Example with Delayed Triggers

You can use setTimeout or any other event to trigger the effect multiple times, ensuring that the animations do not overlap.

// Trigger the firework effect immediately
firework.trigger();

// Trigger the effect again after 2 seconds
setTimeout(() => {
  firework.trigger();
}, 2000);

Advanced Usage Examples

Creating Square Particles with Wide Spread

new ParticleFirework({
  elementId: 'wideSpreadElement',
  duration: 150,
  numParticles: 200,
  colors: ['#ff6b6b', '#ff9f6b', '#ffcd6b', '#cdff6b', '#6bff9f', '#6bcfff', '#6b9fff'],
  size: 15,
  shape: 'square',
  spread: 8
});

Delayed Start with Multiple Colors

new ParticleFirework({
  elementId: 'delayedElement',
  duration: 250,
  delay: 1000,
  numParticles: 100,
  colors: ['#ff6b6b', '#ff9f6b', '#ffcd6b', '#cdff6b', '#6bff9f', '#6bcfff', '#6b9fff'],
  size: 8,
  shape: 'triangle',
  spread: 5
});

Custom SVG Shapes

You can use custom SVG shapes for your particles by specifying an inline SVG string in the customShape option. This gives you the flexibility to create any shape or design for your particles.

Here is how you can create a particle effect using custom SVG shapes:

// Create an instance of ParticleFirework with custom SVG shapes
const firework = new ParticleFirework({
  elementId: 'myElement',
  duration: 150,
  numParticles: 50,
  colors: ["#ff6b6b", "#ff9f6b", "#ffcd6b"],
  size: 30,
  shape: "svg", // Specify the shape as 'svg'
  customShape: `
    <path stroke="none" d="M0 0h24v24H0z" fill="none"/><path d="M6.979 3.074a6 6 0 0 1 4.988 1.425l.037 .033l.034 -.03a6 6 0 0 1 4.733 -1.44l.246 .036a6 6 0 0 1 3.364 10.008l-.18 .185l-.048 .041l-7.45 7.379a1 1 0 0 1 -1.313 .082l-.094 -.082l-7.493 -7.422a6 6 0 0 1 3.176 -10.215z" />
  `, // Custom SVG shape
  spread: 3,
});

// Trigger the particle effect
firework.trigger();

Methods

createParticle(x, y): Creates a particle at the specified (x, y) coordinates. This method is used internally and is typically not called directly.
animateParticles(): Handles the animation loop for the particles. This method is used internally and is typically not called directly.
trigger(): Manually starts the particle effect, ensuring that overlapping animations are avoided.

License

ParticleFirework.js is open-source and available under the MIT License.

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue on the GitHub repository.