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

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! Please feel free to submit a Pull Request.

Changelog

[1.3.0] - 2025-08-06

Features

• New Structure: The project has been completely restructured for better maintainability and scalability.
  • The entire codebase has been migrated from JavaScript to TypeScript, providing improved type safety and developer experience.
  • The code is now organized into modules within the src directory, separating concerns such as canvas creation, particle logic, event handling, and configuration.
• Build System: Introduced Vite for a modern and efficient build process.
  • Added vite.config.ts to manage the build configurations.
  • The library is now bundled into es and umd formats.
• Code Quality: Integrated ESLint and Prettier to enforce a consistent code style and catch potential errors.
  • Added .eslintrc.js and .prettierrc.json configuration files.
• Updated Dependencies: The package.json has been updated with new dev dependencies for TypeScript, ESLint, Prettier, and Vite.

BREAKING CHANGES

• The main entry point of the package has been changed. Please refer to the updated package.json for the new file paths.
• The internal API has been refactored to support the new modular structure.