v2.0.2MIT License

package-particlefx

A lightweight, framework-agnostic JavaScript/TypeScript library that renders interactive particle-based image hover effects using <canvas>. Customize particle behavior with extensive options for physics, visual effects, and user interaction.

What's New in 2.0.2

New Project Structure

Fully rewritten in TypeScript for better type safety and developer experience. Codebase reorganized into modular components — canvas creation, particle logic, event handling, and configuration.

Modern Build System

Switched to Vite for blazing-fast builds. Supports both ES and UMD bundles.

Code Quality

ESLint and Prettier integrated for a consistent and clean code style.

⚠️ Breaking Changes

The main entry point of the package has changed. Refer to the updated package.json for paths.
Internal APIs have been refactored for modularity — usage patterns may require updates.

Features

Image-to-Particles

Convert any image into animated particles

Dynamic Interactions

Particles respond to mouse hover, clicks, and vortex mode

Visual Customization

Filters, hue rotation, and multiple particle shapes

Framework Agnostic

Works with React, Vue, Angular, or vanilla JS

Highly Configurable

Tune physics, appearance, and behavior

Responsive

Adapts to container size automatically

Image Download

Export canvas as PNG with one method call

TypeScript Support

Full types included out of the box

Lightweight

Zero dependencies, pure JS/TS

Installation

Install the package via your preferred package manager.

Terminal

pnpm i image-particles

Quick Start

Get up and running in seconds. Choose your framework below.

index.js

import { createParticleCanvas } from 'package-particlefx';

const container = document.getElementById('my-container');
const particleCanvas = createParticleCanvas(container, {
  preset: 'fireworks',
  width: '100vw',
  height: '100vh',
});

particleCanvas.explodeParticles();
particleCanvas.resetParticles();
particleCanvas.downloadImage('my-particle-art.png');

Configuration

Pass these options as the second argument to createParticleCanvas(container, options).

Option	Type	Default	Description
preset	'fireworks' \| 'snow' \| 'galaxy' \| 'rain'	undefined	Applies a pre-configured set of options.
imageSrc	string	Built-in gradient	Path or data URL of the image to convert.
width	number \| string	400	Canvas width in pixels or CSS units.
height	number \| string	400	Canvas height in pixels or CSS units.
particleGap	number	4	Spacing between particles (lower = more).
mouseForce	number	30	Strength of mouse repulsion effect.
gravity	number	0.08	Force pulling particles back to origin.
noise	number	10	Random movement applied to particles.
clickStrength	number	100	Force applied when clicking on canvas.
hueRotation	number	0	Rotates particle color hue (0–360°).
filter	'none' \| 'grayscale' \| 'sepia' \| 'invert'	'none'	Applies a color filter to particles.
particleShape	'square' \| 'circle' \| 'triangle'	'square'	Shape of individual particles.
vortexMode	boolean	false	Clicks create a vortex instead of a ripple.

API Reference

createParticleCanvas(container, options)

Creates a new particle canvas instance inside the given DOM container element. Returns a ParticleCanvas instance with full control methods.

Instance Methods

resetParticles()

Reset all particles to their original positions.

explodeParticles()

Trigger an explosion effect on all particles.

updateConfig(newOptions)

Merge new options into the current configuration and re-render.

downloadImage(filename?)

Export the current canvas state as a PNG file.

destroy()

Remove the canvas, event listeners, and clean up resources.

getParticleCount()

Returns the current number of active particles.

getConfig()

Returns the current configuration object.

stopAnimation()

Pause the animation loop.

startAnimation()

Resume the animation loop.

Performance Tips

Higher particleGap
Use values of 4–8 for better performance on lower-end devices.
Smaller images
Smaller source images = faster loading and fewer particles.
Avoid full-screen on mobile
Full-viewport canvases can be heavy on mobile GPUs.

Browser Support

Chrome

60+

Firefox

55+

Safari

12+

Edge

79+

Contributing

Contributions are welcome! Here's how you can get started:

Fork the repository and clone it to your local machine.
Create a new branch for your changes:
Terminal
1git checkout -b my-feature-branch
Link the package to a local project for testing:
Terminal
1# In this project's directory 2npm link 3 4# In your other project's directory 5npm link package-particlefx
Make your changes and commit them with a clear message.
Push your branch and open a Pull Request.