✨ microsparks

Ultra-lightweight, zero-dependency GPU-accelerated HTML5 2D Canvas micro-particle engine for web UI feedback with 0KB downloaded assets.

Live Demo: https://microsparks.vercel.app

---

⚡ Why microsparks?

Traditional particle libraries are heavy (50KB–150KB), introduce complex canvas setups, cause layout shifts, or continuously consume CPU/GPU resources even when idle.

microsparks is a < 2.5 KB gzipped micro-engine that manages a single transparent overlay canvas. It renders razor-sharp, 60 FPS particle bursts for buttons, likes, upvotes, and celebrations, and automatically pauses the animation loop when particles expire.

• 🚀 0KB Image Assets: Pure 2D Canvas vector math for high performance.
• 📐 High-DPI Retina Sharpness: Automatic devicePixelRatio scaling.
• ⚡ Zero Layout Shift: Overlay canvas attached to body with pointer-events: none.
• 💤 Zero Idle Overhead: Animation loop automatically pauses when active particle count drops to 0.
• 🪶 Micro Footprint: Under 2.5 KB gzipped!
• ⚛️ React & Vanilla JS: Works everywhere (React, Vue, Svelte, Next.js, or plain JS).

---

📦 Installation

npm install microsparks
# or
pnpm add microsparks
# or
yarn add microsparks

---

🚀 Quick Start

1. Vanilla JS / TypeScript

import { sparks } from 'microsparks';

// Trigger preset particle bursts on click events
document.querySelector('#btn').addEventListener('click', (e) => {
  sparks.burst({ target: e });
});

// Built-in presets
sparks.stars();
sparks.confetti();
sparks.heart();
sparks.electric();
sparks.coin();
sparks.powerUp();
sparks.laser();
sparks.explode();

2. React / Next.js App Router (useMicroSparks)

Tip

microsparks is 100% SSR-safe. In Next.js App Router (Next.js 13/14/15/16), simply use 'use client' on components importing UI hooks.

'use client';

import React from 'react';
import { useMicroSparks } from 'microsparks/react';

export function ActionButton() {
  const { stars, confetti } = useMicroSparks();

  return (
    <button onClick={(e) => stars({ target: e })}>
      Sparkle Action
    </button>
  );
}

---

🎛️ 9 Built-in Presets Matrix

Method	Shape	Physics Behavior	Use Case
sparks.burst()	Circular sparks	High-velocity radial explosion	Primary buttons, submit actions
sparks.stars()	5-point stars	Twinkling spin & upward lift	Favorites, reviews, bookmarks
sparks.confetti()	Rectangular slips	Fluttering tumble with gravity	Success modals, milestones
sparks.heart()	Hearts	Soft upward float with scale pulse	Likes, upvotes, appreciation
sparks.electric()	Concentric rings	High-speed ring snap expansion	Toggle switches, power actions
sparks.coin()	Gold coins	Upward bounce with spin	Reward pickup, points earned
sparks.powerUp()	Glowing specks	Rising energetic vortex	Level up, feature unlock
sparks.laser()	Streak lines	Linear high-speed ray	Arcade games, delete actions
sparks.explode()	Multi-shape	Heavy shockwave explosion	Victory, destructive actions

---

🧪 Custom Particle Trigger API

You can customize particle bursts dynamically:

import { sparks } from 'microsparks';

sparks.trigger({
  target: { x: 400, y: 300 }, // Explicit {x,y}, MouseEvent, or HTMLElement
  count: 25,
  shape: 'star', // 'circle' | 'star' | 'heart' | 'rect' | 'ring' | 'line' | 'coin'
  minSize: 6,
  maxSize: 14,
  minSpeed: 3,
  maxSpeed: 8,
  gravity: 0.15,
  duration: 0.8,
  colors: ['#38bdf8', '#06b6d4', '#f43f5e', '#10b981']
});

---

📄 License

MIT © fullstackusama