sparklefall

v1.0.1

Published

3 months ago

Beautiful, customizable falling sparkle animations for your website. Zero dependencies, easy to use.

Downloads

0High
0Medium
0Low

sparkle animation falling particle effects sparkles visual-effects ui frontend vanilla-js zero-dependency emoji confetti celebration

✨ SparkleFall

Beautiful, customizable falling sparkle animations for your website. Zero dependencies, easy to use, and fully customizable.

npm version license size

✨ Features

🎨 Fully Customizable - Control colors, sizes, speed, and more
🚀 Zero Dependencies - Pure vanilla JavaScript, no frameworks needed
📦 Tiny Size - Less than 3KB minified and gzipped
🎯 Simple API - Get started with just one line of code
📱 Mobile Friendly - Optimized performance on all devices
🔧 TypeScript Support - Full type definitions included
🌈 Multiple Effects - Wind, spin, burst modes and more

📦 Installation

NPM

npm install sparklefall

Yarn

yarn add sparklefall

CDN

<!-- Latest version -->
<link rel="stylesheet" href="https://unpkg.com/sparklefall@latest/dist/sparklefall.css">
<script src="https://unpkg.com/sparklefall@latest/dist/sparklefall.min.js"></script>

<!-- Specific version -->
<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/sparklefall.css">
<script src="https://unpkg.com/[email protected]/dist/sparklefall.min.js"></script>

🚀 Quick Start

Basic Usage

// ES6 Modules
import SparkleFall from 'sparklefall';
import 'sparklefall/styles.css';

// CommonJS
const SparkleFall = require('sparklefall');
// CSS via bundler import or add <link> to dist/sparklefall.css

// Create sparkles with default settings
const sparkles = new SparkleFall({ injectStyles: true });

HTML Script Tag

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://unpkg.com/sparklefall@latest/dist/sparklefall.css">
  <script src="https://unpkg.com/sparklefall@latest/dist/sparklefall.min.js"></script>
</head>
<body>
  <script>
    // SparkleFall is available globally
    const sparkles = new SparkleFall({ injectStyles: true });
  </script>
</body>
</html>

⚙️ Configuration

All Options

const sparkles = new SparkleFall({
  // Container
  container: document.body,     // Element or selector for sparkle container
  
  // Timing
  interval: 800,                // Time between new sparkles (ms)
  duration: 5000,               // How long sparkles remain visible (ms)
  
  // Appearance
  sparkles: ['✨', '⭐', '💫', '🌟'],  // Array of sparkle characters
  colors: null,                 // null for emoji colors, or ['#FFD700', '#FFF']
  minSize: 10,                  // Minimum sparkle size (px)
  maxSize: 30,                  // Maximum sparkle size (px)
  
  // Animation
  minDuration: 2,               // Minimum fall time (seconds)
  maxDuration: 5,               // Maximum fall time (seconds)
  wind: 0,                      // Wind effect (-1 to 1)
  spin: true,                   // Enable rotation
  
  // Performance
  maxSparkles: 50,              // Max sparkles on screen
  autoStart: true,              // Start automatically
  zIndex: 9999                  // Z-index of sparkle container
});

🎨 Examples

Custom Colors

const goldSparkles = new SparkleFall({
  colors: ['#FFD700', '#FFA500', '#FF8C00'],
  sparkles: ['●', '◆', '■', '▲'],
  minSize: 8,
  maxSize: 20
});

Holiday Theme

const holidaySparkles = new SparkleFall({
  sparkles: ['❄️', '🎄', '🎅', '🎁', '⭐'],
  interval: 600,
  wind: 0.3,
  spin: true
});

Fast and Minimal

const minimalSparkles = new SparkleFall({
  sparkles: ['·'],
  colors: ['rgba(255,255,255,0.8)'],
  minSize: 2,
  maxSize: 4,
  interval: 100,
  minDuration: 1,
  maxDuration: 2,
  maxSparkles: 100
});

Wind Effect

const windySparkles = new SparkleFall({
  wind: 0.5,  // Blow right
  spin: true,
  minDuration: 3,
  maxDuration: 6
});

🎮 API Methods

start()

Start the sparkle animation

sparkles.start();

stop()

Stop creating new sparkles (existing ones continue falling)

sparkles.stop();

clear()

Remove all sparkles immediately

sparkles.clear();

burst(count)

Create a burst of sparkles

sparkles.burst(20); // Create 20 sparkles instantly

updateConfig(options)

Update configuration on the fly

sparkles.updateConfig({
  colors: ['#FF0000', '#00FF00', '#0000FF'],
  wind: 0.5
});

destroy()

Clean up and remove the instance

sparkles.destroy();

🎯 Use Cases

Page Load Celebration

// Sparkles for 5 seconds on page load
const celebration = new SparkleFall();
setTimeout(() => celebration.destroy(), 5000);

Button Click Effect

document.querySelector('#special-button').addEventListener('click', () => {
  const sparkles = new SparkleFall({
    container: '#special-button',
    maxSparkles: 30
  });
  sparkles.burst(30);
  setTimeout(() => sparkles.destroy(), 3000);
});

Scroll Triggered

let sparkles;
window.addEventListener('scroll', () => {
  if (window.scrollY > 500 && !sparkles) {
    sparkles = new SparkleFall();
  }
});

Interactive Following

document.addEventListener('mousemove', (e) => {
  const sparkle = new SparkleFall({
    container: document.body,
    maxSparkles: 5,
    interval: 100
  });
  
  // Position sparkles at cursor
  sparkle.sparkleContainer.style.left = e.clientX + 'px';
  sparkle.sparkleContainer.style.top = e.clientY + 'px';
  sparkle.sparkleContainer.style.width = '10px';
  sparkle.sparkleContainer.style.height = '10px';
  
  sparkle.burst(1);
  setTimeout(() => sparkle.destroy(), 1000);
});

🌐 React Component Example

import React, { useEffect, useRef } from 'react';
import SparkleFall from 'sparklefall';

const SparkleContainer = ({ children, ...options }) => {
  const containerRef = useRef(null);
  const sparklesRef = useRef(null);
  
  useEffect(() => {
    if (containerRef.current) {
      sparklesRef.current = new SparkleFall({
        container: containerRef.current,
        ...options
      });
    }
    
    return () => {
      if (sparklesRef.current) {
        sparklesRef.current.destroy();
      }
    };
  }, []);
  
  return (
    <div ref={containerRef} style={{ position: 'relative' }}>
      {children}
    </div>
  );
};

// Usage
<SparkleContainer 
  sparkles={['🌟', '✨']}
  interval={500}
  maxSparkles={30}
>
  <h1>Sparkly Content!</h1>
</SparkleContainer>

🎭 Vue Component Example

<template>
  <div ref="sparkleContainer">
    <slot></slot>
  </div>
</template>

<script>
import SparkleFall from 'sparklefall';

export default {
  props: {
    options: {
      type: Object,
      default: () => ({})
    }
  },
  mounted() {
    this.sparkles = new SparkleFall({
      container: this.$refs.sparkleContainer,
      ...this.options
    });
  },
  beforeDestroy() {
    if (this.sparkles) {
      this.sparkles.destroy();
    }
  }
};
</script>

📊 Performance Tips

Limit Max Sparkles: Keep maxSparkles under 100 for smooth performance
Adjust Interval: Higher interval values = fewer sparkles = better performance
Container Size: Smaller containers need fewer sparkles
Mobile: Consider reducing sparkles on mobile devices

const isMobile = window.innerWidth < 768;
const sparkles = new SparkleFall({
  maxSparkles: isMobile ? 20 : 50,
  interval: isMobile ? 1200 : 800
});

🔧 Browser Support

Chrome 60+
Firefox 60+
Safari 12+
Edge 79+
iOS Safari 12+
Chrome for Android

📝 License

MIT License - feel free to use in personal and commercial projects.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🎮 Live Demo

Check out the interactive demo with live controls and presets!

🐛 Issues

Found a bug? Please create an issue with a description and steps to reproduce.

💖 Support

If you like this project, please consider:

⭐ Starring the repository
🐦 Sharing on social media

🚀 Roadmap

[ ] Custom SVG shapes support
[ ] Particle physics mode
[ ] 3D rotation effects
[ ] Performance mode for low-end devices
[ ] Accessibility options
[ ] Canvas rendering mode
[ ] WebGL rendering mode

Made with ✨ by Theresa Summa