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. Easily integrate into React, Vue, or plain HTML projects by passing a DOM container element.

---

🚀 What's New in 2.0.2

✨ Features

• 🔧 New Project Structure

  • Fully rewritten in TypeScript for better type safety and developer experience.
  • Codebase reorganized into modular components within src/:
    • Canvas creation
    • Particle logic
    • Event handling
    • Configuration

• ⚡ Modern Build System

  • Switched to Vite for blazing-fast builds.
  • Supports both ES and UMD bundles.
  • Introduced vite.config.ts.

• 🧼 Code Quality Improvements

  • ESLint and Prettier integrated for a consistent and clean code style.
  • Added .eslintrc.js and .prettierrc.json.

• 📦 Updated Dependencies

  • Development dependencies now include TypeScript, ESLint, Prettier, and Vite.

⚠️ 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 (grayscale, sepia, invert), hue rotation, shapes
• Framework Agnostic: Works with React, Vue, Angular, or vanilla JS
• Highly Configurable: Tune physics, appearance, and behavior
• Responsive: Adapts to container size
• Image Download: Export canvas as PNG
• TypeScript Support: Full types included
• Lightweight: Zero dependencies, pure JS/TS

---

Installation

npm install package-particlefx

---

Quick Start

Vanilla JavaScript

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');

React

import React, { useRef, useEffect, useState } from 'react';
import { createParticleCanvas } from 'package-particlefx';

function ParticleComponent() {
  const containerRef = useRef(null);
  const particleCanvasRef = useRef(null);
  const [config, setConfig] = useState({
    preset: 'galaxy',
    width: '100%',
    height: '400px',
  });

  useEffect(() => {
    if (containerRef.current) {
      particleCanvasRef.current = createParticleCanvas(containerRef.current, config);
    }

    return () => {
      particleCanvasRef.current?.destroy();
    };
  }, [config]);

  return (
    <div>
      <div ref={containerRef} style={{ width: '100%', height: '400px' }} />
      <button onClick={() => particleCanvasRef.current?.explodeParticles()}>Explode</button>
      <button onClick={() => particleCanvasRef.current?.resetParticles()}>Reset</button>
      <button onClick={() => particleCanvasRef.current?.downloadImage()}>Download</button>
      <button onClick={() => setConfig(prev => ({ ...prev, preset: 'snow' }))}>Change to Snow</button>
    </div>
  );
}

export default ParticleComponent;

---

Configuration 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 a string with units (e.g., '100vw').
height	number | string	400	Canvas height in pixels or a string with units (e.g., '100vh').
particleGap	number	4	Spacing between particles (lower = more particles).
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 the hue of particle colors (0-360 degrees).
filter	'none' | 'grayscale' | 'sepia' | 'invert'	'none'	Applies a color filter to particles.
particleShape	'square' | 'circle' | 'triangle'	'square'	Shape of individual particles.
vortexMode	boolean	false	If true, clicks create a vortex effect instead of a ripple.

---

API Reference

createParticleCanvas(container, options)

Creates a new particle canvas instance.

Returns: ParticleCanvas instance

ParticleCanvas Methods

• resetParticles()
• explodeParticles()
• updateConfig(newOptions)
• downloadImage(filename?: string)
• destroy()
• getParticleCount()
• getConfig()
• stopAnimation() / startAnimation()

---

Performance Tips

• Use higher particleGap (4-8) for better performance.
• Smaller images = faster loading.
• Avoid full-screen canvas on mobile for performance.

---

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

---

License

MIT © Anmol Singh

---

Contributing

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

1. Fork the repository and clone it to your local machine.
2. Create a new branch for your changes:

   git checkout -b my-feature-branch

3. Link the package to a local project for testing:
   • In this project's directory, run npm link.
   • In your other project's directory, run npm link package-particlefx.
4. Make your changes and commit them with a clear message.
5. Push your branch and open a Pull Request.

Please feel free to submit a Pull Request!