🎉 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

``bash
npm install falling-animation
`

Or use via CDN:

`html

`

🚀 Quick Start

$3

`javascript
import { FallingAnimation } from 'falling-animation';

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

$3

`html


`

📖 API Reference

$3

`typescript
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;
}
`

$3

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

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

// Custom HTML
{ type: 'html', content: '

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

$3

| 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 |

$3

`javascript
// 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

$3

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

$3

`javascript
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
});
`

$3

`javascript
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
});
`

$3

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

$3

`javascript
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:

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

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

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

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

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

---

🎆 Fireworks

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

$3

`javascript
import { Fireworks } from 'falling-animation';

const fireworks = new Fireworks();
`

$3

`typescript
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;
}
`

$3

`javascript
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();
`

$3

$3

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

$3

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.

`javascript
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.

`javascript
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.

`javascript
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!

`javascript
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)?

`javascript
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.