🎉 Falling Animation

A lightweight, customizable falling objects animation library for the web. Create beautiful falling effects like snow, leaves, confetti, and realistic fireworks!

✨ Features

• 🪶 Lightweight - No dependencies, < 15KB gzipped
• 🎨 Customizable - Full control over speed, size, animation, and more
• 🎭 8 Animation Types - fall, swing, rotate, flutter, spiral, tumble, zigzag, float
• 🎆 Fireworks - Realistic rockets shooting up and exploding into colorful particles
• 📱 Responsive - Automatically adapts to container size
• 🖼️ Multiple Object Types - Emojis, images, or custom HTML
• ⚡ Performant - Uses requestAnimationFrame and CSS transforms
• 📦 TypeScript - Full type definitions included
• 🌐 Universal - Works with ESM, CJS, and UMD

📦 Installation

npm install falling-animation

Or use via CDN:

<script src="https://unpkg.com/falling-animation/dist/falling-animation.umd.min.js"></script>

🚀 Quick Start

ES Modules

import { FallingAnimation } from 'falling-animation';

const falling = new FallingAnimation({
  objects: [
    { type: 'emoji', content: '❄️' },
    { type: 'emoji', content: '🌸' }
  ]
});

CDN / UMD

<script src="https://unpkg.com/falling-animation/dist/falling-animation.umd.min.js"></script>
<script>
  const falling = new FallingAnimation.FallingAnimation({
    objects: [{ type: 'emoji', content: '🍁' }]
  });
</script>

📖 API Reference

Constructor Options

interface FallingAnimationOptions {
  // Required: Objects to fall
  objects: FallingObject[];
  
  // Container element or selector (default: document.body)
  container?: HTMLElement | string;
  
  // Falling speed in px/frame (default: { min: 2, max: 5 })
  speed?: { min: number; max: number };
  
  // Objects spawned per second (default: 3)
  spawnRate?: number;
  
  // Maximum concurrent particles (default: 50)
  maxParticles?: number;
  
  // Animation type(s) (default: 'fall')
  animation?: AnimationType | AnimationType[];
  
  // Object size in px (default: { min: 20, max: 40 })
  size?: { min: number; max: number };
  
  // Object opacity (default: { min: 0.6, max: 1 })
  opacity?: { min: number; max: number };
  
  // Wind effect from -1 to 1 (default: 0)
  wind?: number;
  
  // Auto start animation (default: true)
  autoStart?: boolean;
  
  // Z-index for container (default: 9999)
  zIndex?: number;
  
  // Enable responsive behavior (default: true)
  responsive?: boolean;
}

Object Types

// Emoji
{ type: 'emoji', content: '🍁' }

// Image
{ type: 'image', src: '/path/to/image.png' }

// Custom HTML
{ type: 'html', content: '<div class="custom">★</div>' }

// With weight for random selection
{ type: 'emoji', content: '❄️', weight: 3 }

Animation Types

| Type | Description | |------|-------------| | fall | Simple vertical fall | | swing | Pendulum-like swinging | | rotate | Continuous 360° rotation | | flutter | Butterfly-like fluttering | | spiral | Spiraling down pattern | | tumble | Chaotic tumbling motion | | zigzag | Zigzag falling pattern | | float | Slow floating descent |

Methods

// Control methods
falling.start();    // Start the animation
falling.stop();     // Stop and clear all particles
falling.pause();    // Pause animation (keeps particles)
falling.resume();   // Resume paused animation
falling.destroy();  // Clean up and remove from DOM

// Update options dynamically
falling.setOptions({
  speed: { min: 5, max: 10 },
  spawnRate: 5,
  animation: 'tumble'
});

// Get state
falling.getParticleCount();  // Current particle count
falling.getIsRunning();      // Is animation running?
falling.getIsPaused();       // Is animation paused?

🎨 Examples

Snow Effect

new FallingAnimation({
  objects: [
    { type: 'emoji', content: '❄️' },
    { type: 'emoji', content: '❅' },
    { type: 'emoji', content: '❆' }
  ],
  animation: 'float',
  speed: { min: 1, max: 3 },
  size: { min: 15, max: 35 }
});

Autumn Leaves

new FallingAnimation({
  objects: [
    { type: 'emoji', content: '🍁', weight: 3 },
    { type: 'emoji', content: '🍂', weight: 2 },
    { type: 'emoji', content: '🍃', weight: 1 }
  ],
  animation: 'swing',
  speed: { min: 2, max: 4 },
  wind: 0.3
});

Confetti Party

new FallingAnimation({
  objects: [
    { type: 'emoji', content: '🎊' },
    { type: 'emoji', content: '🎉' },
    { type: 'emoji', content: '✨' }
  ],
  animation: ['tumble', 'rotate', 'zigzag'],
  speed: { min: 3, max: 6 },
  spawnRate: 10,
  maxParticles: 100
});

Bounded Container

new FallingAnimation({
  container: '#my-container',  // or document.getElementById('my-container')
  objects: [{ type: 'emoji', content: '⭐' }],
  animation: 'spiral',
  zIndex: 100
});

Using Images

new FallingAnimation({
  objects: [
    { type: 'image', src: '/images/snowflake.png' },
    { type: 'image', src: '/images/star.png' }
  ],
  size: { min: 30, max: 50 }
});

🔧 TypeScript

Full TypeScript support with exported types:

// For falling effects only
import { FallingAnimation, FallingAnimationOptions } from 'falling-animation';

const falling = new FallingAnimation({
  objects: [{ type: 'emoji', content: '🌟' }],
  animation: 'rotate'
});

// For fireworks only
import { Fireworks, FireworksOptions } from 'falling-animation';

const fw = new Fireworks({
  launchRate: 2,
  particlesPerExplosion: 60
});

// Both together
import { FallingAnimation, Fireworks } from 'falling-animation';

🎆 Fireworks

Create realistic firework effects with rockets shooting up and exploding into colorful particles!

Quick Start

import { Fireworks } from 'falling-animation';

const fireworks = new Fireworks();

Fireworks Options

interface FireworksOptions {
  // Container element or selector (default: document.body)
  container?: HTMLElement | string;
  
  // Colors for fireworks (default: 10 festive colors)
  colors?: string[];
  
  // Rockets per second (default: 0.5)
  launchRate?: number;
  
  // Particles per explosion (default: 50)
  particlesPerExplosion?: number;
  
  // Rocket speed range (default: { min: 7, max: 12 })
  rocketSpeed?: { min: number; max: number };
  
  // Explosion particle speed (default: { min: 1, max: 6 })
  explosionSpeed?: { min: number; max: number };
  
  // Particle size in px (default: { min: 2, max: 6 })
  particleSize?: { min: number; max: number };
  
  // Particle lifetime in ms (default: { min: 1000, max: 2000 })
  particleLifetime?: { min: number; max: number };
  
  // Gravity strength (default: 0.1)
  gravity?: number;
  
  // Auto start (default: true)
  autoStart?: boolean;
  
  // Explosion pattern (default: 'random')
  // Values: 'random' | 'circular' | 'double' | 'embers' | 'heart' | 'star' | 'ring' | 'palm' | 'willow' | 'chrysanthemum'
  // Can also be an array: ['double', 'heart']
  explosionPattern?: ExplosionPattern | ExplosionPattern[];

  // Z-index (default: 9999)
  zIndex?: number;
}

Fireworks Methods

const fw = new Fireworks();

// Control methods
fw.start();     // Start continuous fireworks
fw.stop();      // Stop launching new rockets
fw.clear();     // Clear all particles
fw.destroy();   // Clean up completely

// Manual launch
fw.launch();    // Launch single firework
fw.burst(5);    // Launch 5 fireworks at once

// Update options dynamically
fw.setOptions({
  launchRate: 2,
  particlesPerExplosion: 80
});

// Get state
fw.getParticleCount();
fw.getIsRunning();

Fireworks Examples

Explosion Patterns

You can choose from 9 different explosion patterns or use a random mix!

• random: Randomly selects a pattern for each explosion (default)
• circular: Standard circular explosion
• double: Spectacular 2-stage explosion (particles explode again!)
• waterfall: Waterfall effect (gentle up, heavy rain down)
• embers: Slow-falling, micro-particles (Tàn Lửa)
• heart: ❤️ Heart shape
• star: ⭐ Star shape
• ring: 💍 Ring shape
• palm: 🌴 Palm tree effect
• willow: 🌳 Trailing willow effect
• chrysanthemum: 🌼 Dense spherical burst

✨ Recommended Presets

Here are some beautiful configurations to get you started:

1. The Grand Finale (Spectacular Mix)

Perfect for big celebrations. Uses double explosions and a mix of random patterns.

const fireworks = new Fireworks({
  launchRate: 2,
  particlesPerExplosion: 50,
  explosionPattern: ['double', 'random'], // Mix of single and double explosions
  rocketSpeed: { min: 12, max: 18 },
  explosionSpeed: { min: 3, max: 9 }
});

2. Romantic Hearts

A gentle stream of heart-shaped fireworks, great for weddings or Valentine's.

new Fireworks({
  launchRate: 1,
  particlesPerExplosion: 40,
  explosionPattern: 'heart',
  colors: ['#ff0000', '#ff69b4', '#ffffff'], // Red, Pink, White
  gravity: 0.05, // Slower fall
  rocketSpeed: { min: 10, max: 12 }
});

3. Gentle Embers (Tàn Lửa)

Soft, floating micro-particles that drift slowly. Very atmospheric.

new Fireworks({
  launchRate: 3,
  explosionPattern: 'embers',
  rocketSpeed: { min: 8, max: 12 },
  particleLifetime: { min: 2000, max: 4000 },
  gravity: 0.05
});

4. New Year Countdown (Intense)

High density, fast-paced action!

const fw = new Fireworks({
  launchRate: 4,               // Fast launch
  particlesPerExplosion: 60,   // Dense explosions
  explosionPattern: 'random',
  explosionSpeed: { min: 5, max: 10 }
});

// Launch a massive burst manually when the timer hits zero!
// fw.burst(15);

5. Single Shot (Manual Control)

Want to trigger fireworks manually (e.g., on button click)?

const fw = new Fireworks({
  autoStart: false  // 1. Disable auto-start
});

// 2. Trigger manually whenever you want (e.g. onClick)
fw.launch(); // Launches 1 rocket
// or
fw.burst(5); // Launches 5 rockets at once

📄 License

MIT © phongdh

🙏 Contributing

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

I'm currently figuring out how to implement the Waterfall or Weeping Willow effect properly. If you have experience with these physics/visuals, I'd love your help! Please feel free to open a Pull Request.