seasonalfx

v0.2.2

Published

11 days ago

Production-grade, multi-season ambient visual effects library for modern web applications

SeasonalFX - Snow Effect, Confetti, and Seasonal Animations for Web

🎨 Production-grade snow effects, confetti animations, falling leaves, and seasonal particle effects for modern web applications. Lightweight, accessible, and zero dependencies.

SeasonalFX Demo

🔗 Quick Links

🌐 Live Demo - See it in action
🎮 Interactive Demo - Play with all effects
📚 Documentation - Complete API reference
📦 NPM Package - Install via npm
💻 GitHub Repository - Source code
🐛 Issue Tracker - Report bugs
👤 Author Portfolio - Nishikanta Ray

Add beautiful snow effects, confetti animations, falling autumn leaves, and spring cherry blossoms to your website with just a few lines of code. Perfect for holiday themes, celebrations, seasonal websites, and special events.

✨ Features

🌨️ Realistic Snow Effect - Beautiful falling snowflakes animation for winter themes
🎉 Confetti Animations - Celebration effects for events, achievements, and milestones
🍂 Autumn Leaves - Falling leaves effect with realistic physics
🌸 Spring Petals - Cherry blossom and flower petal animations
⚡ Lightning Fast - Under 5KB gzipped, 60 FPS performance
♿ Accessibility First - Respects prefers-reduced-motion, mobile-optimized
🔧 Framework Agnostic - Works with React, Vue, Angular, Svelte, or vanilla JS
🌍 SSR Safe - Compatible with Next.js, Nuxt, Astro, and other SSR frameworks
📦 Zero Dependencies - No jQuery, no bloat, just pure performance
🎨 Customizable - Control intensity, colors, speed, and particle count

Installation

Via NPM

npm install seasonalfx

Or with yarn:

yarn add seasonalfx

Via CDN (No Build Required!)

🌐 Your package is live on all major CDNs!

<!-- unpkg CDN -->
<script src="https://unpkg.com/[email protected]/dist/index.umd.min.js"></script>

<!-- jsDelivr CDN (recommended - faster) -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/index.umd.min.js"></script>

<!-- Always get latest version (use @latest) -->
<script src="https://cdn.jsdelivr.net/npm/seasonalfx@latest/dist/index.umd.min.js"></script>

Complete CDN Example:

<!DOCTYPE html>
<html>
<head>
  <title>Snow Effect Demo</title>
</head>
<body>
  <div id="snow-container" style="position: fixed; top: 0; left: 0; width: 100%; height: 100%; pointer-events: none;"></div>
  
  <!-- Load from CDN -->
  <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/index.umd.min.js"></script>
  
  <script>
    // Create beautiful snow effect
    const fx = new SeasonalFX.SeasonalFX('snow-container', {
      season: 'winter',
      intensity: 'moderate'
    });
    fx.start();
  </script>
</body>
</html>

Try it now: Copy the code above and open it in your browser - instant snow effect! ❄️

Quick Start

Vanilla JavaScript

import { createSeasonalFX } from 'seasonalfx';

const fx = createSeasonalFX({
  target: document.body,
  autoSeason: true,
  intensity: 'subtle',
});

fx.start();

React

import { SeasonalFX } from 'seasonalfx/react';

function App() {
  return (
    <div style={{ position: 'relative', height: '100vh' }}>
      <SeasonalFX autoSeason intensity="subtle" />
      <h1>Your Content Here</h1>
    </div>
  );
}

Seasons & Effects

❄️ Winter

Gentle snowfall with size variance and horizontal drift

fx.setSeason('winter', {
  variant: 'light',      // 'light' | 'holiday' | 'blizzard'
  intensity: 'subtle',
});

🌸 Spring

Floating petals with swirling motion

fx.setSeason('spring', {
  variant: 'sakura',     // 'sakura' | 'softPetals' | 'pollen'
  intensity: 'subtle',
});

☀️ Summer

Minimal dust particles or fireflies

fx.setSeason('summer', {
  variant: 'sunDust',    // 'heatHaze' | 'sunDust' | 'fireflies'
  intensity: 'minimal',
});

🍂 Autumn

Falling leaves with tumbling motion

fx.setSeason('autumn', {
  variant: 'maple',      // 'maple' | 'dryLeaves' | 'windy'
  intensity: 'subtle',
});

🎉 Event

Time-boxed confetti for celebrations

fx.setSeason('event', {
  variant: 'celebration', // 'newYear' | 'celebration' | 'launch'
  duration: 5000,         // Auto-stop after 5 seconds
});

Configuration

Full Configuration Options

interface SeasonalFXConfig {
  // Required
  target: HTMLElement;
  
  // Automatic season detection
  autoSeason?: boolean;           // Default: true
  
  // Manual season override
  season?: Season;
  
  // Season-specific config
  seasonConfig?: {
    winter?: { variant?: 'light' | 'holiday' | 'blizzard', intensity?: Intensity },
    spring?: { variant?: 'sakura' | 'softPetals' | 'pollen', intensity?: Intensity },
    // ...
  };
  
  // Effect intensity
  intensity?: 'minimal' | 'subtle' | 'moderate' | 'bold';  // Default: 'subtle'
  
  // Performance
  maxFPS?: number;                // Default: 30
  
  // Accessibility & UX
  disableOnMobile?: boolean;      // Default: true
  respectReducedMotion?: boolean; // Default: true
  
  // Regional customization
  regionalConfig?: RegionalSeasonConfig;
  
  // Debug mode
  debug?: boolean;                // Default: false
}

Intensity Levels

minimal: 10-15 particles, very subtle
subtle: 30-40 particles, ambient (recommended)
moderate: 60-80 particles, noticeable
bold: 100+ particles, prominent

API Reference

Core Methods

const fx = createSeasonalFX(config);

// Control
fx.start();                           // Start effects
fx.pause();                           // Pause (can resume)
fx.resume();                          // Resume paused effects
fx.destroy();                         // Clean up and remove

// Season control
fx.setSeason('winter', { 
  variant: 'blizzard',
  intensity: 'moderate'
});

// Configuration
fx.updateConfig({ 
  maxFPS: 60,
  intensity: 'bold'
});

// Performance monitoring
const metrics = fx.getMetrics();
console.log(metrics.fps);             // Current FPS
console.log(metrics.particleCount);   // Active particles
console.log(metrics.renderTime);      // Render time in ms

// State
fx.isRunning();                       // true/false

React Hook

import { useSeasonalFX } from 'seasonalfx/react';

function Component() {
  const containerRef = useRef(null);
  const fx = useSeasonalFX(containerRef, {
    autoSeason: true,
    intensity: 'subtle',
  });

  return (
    <div ref={containerRef}>
      <button onClick={() => fx?.setSeason('winter')}>
        Winter Mode
      </button>
    </div>
  );
}

Accessibility

SeasonalFX is built with accessibility as a core principle:

✅ Automatically respects prefers-reduced-motion
✅ Can be disabled on mobile devices
✅ No layout shift or content obstruction
✅ Pointer events disabled (non-interactive)
✅ Optional static fallback mode

Manual Accessibility Control

// Check user preferences
import { prefersReducedMotion } from 'seasonalfx';

if (!prefersReducedMotion()) {
  fx.start();
}

// Or let the library handle it automatically
const fx = createSeasonalFX({
  target: document.body,
  respectReducedMotion: true, // Default: true
});

Performance

SeasonalFX is optimized for production:

📦 Bundle Size: Core engine < 5KB gzipped
⚡ Rendering: Uses requestAnimationFrame with FPS throttling
🎯 Particle Limits: Intelligent caps per intensity level
🔄 Resource Management: Automatic cleanup on destroy
📊 Monitoring: Built-in performance metrics

Performance Tips

// Limit FPS for better performance
createSeasonalFX({
  target: document.body,
  maxFPS: 30,  // Default is 30, reduce further if needed
});

// Use minimal intensity on mobile
createSeasonalFX({
  target: document.body,
  intensity: isMobileDevice() ? 'minimal' : 'subtle',
});

// Monitor performance
const metrics = fx.getMetrics();
if (metrics.fps < 20) {
  fx.updateConfig({ intensity: 'minimal' });
}

SSR Support

SeasonalFX is fully SSR-safe:

Next.js

'use client';  // Mark as client component

import { SeasonalFX } from 'seasonalfx/react';

export default function Page() {
  return (
    <div style={{ position: 'relative' }}>
      <SeasonalFX autoSeason intensity="subtle" />
      <YourContent />
    </div>
  );
}

Astro

---
import { SeasonalFX } from 'seasonalfx/react';
---

<div style="position: relative;">
  <SeasonalFX client:load autoSeason intensity="subtle" />
  <YourContent />
</div>

Regional Season Configuration

Customize season dates for different hemispheres:

const southernHemisphereConfig = {
  spring: [[9, 11]],   // Sep - Nov
  summer: [[12, 2]],   // Dec - Feb
  autumn: [[3, 5]],    // Mar - May
  winter: [[6, 8]],    // Jun - Aug
};

createSeasonalFX({
  target: document.body,
  autoSeason: true,
  regionalConfig: southernHemisphereConfig,
});

Examples

Marketing Page with Event Confetti

const fx = createSeasonalFX({
  target: document.getElementById('hero'),
  season: 'event',
  seasonConfig: {
    event: {
      variant: 'launch',
      duration: 5000,  // Auto-stop after 5 seconds
    }
  }
});

fx.start();  // Confetti bursts and auto-stops

Season Selector UI

const seasons = ['winter', 'spring', 'summer', 'autumn'];

seasons.forEach(season => {
  document.getElementById(`btn-${season}`).addEventListener('click', () => {
    fx.setSeason(season);
  });
});

Performance Dashboard

setInterval(() => {
  const metrics = fx.getMetrics();
  document.getElementById('fps').textContent = metrics.fps;
  document.getElementById('particles').textContent = metrics.particleCount;
  document.getElementById('render-time').textContent = metrics.renderTime.toFixed(2);
}, 1000);

Browser Support

✅ Chrome/Edge (latest)
✅ Firefox (latest)
✅ Safari (latest)
✅ Mobile browsers

Requires modern browser with:

Canvas API
requestAnimationFrame
ES2020 features

📄 License

🤝 Contributing

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

📞 Support & Resources

🌐 Live Demo: seasonalfx.nishikanta.in
📖 Documentation: seasonalfx.nishikanta.in/docs.html
🎮 Interactive Demo: seasonalfx.nishikanta.in/demo
📦 NPM Package: npmjs.com/package/seasonalfx
💻 GitHub: github.com/NishikantaRay/seasonalfx
🐛 Issue Tracker: github.com/NishikantaRay/seasonalfx/issues
💬 Discussions: github.com/NishikantaRay/seasonalfx/discussions
👤 Author: nishikanta.in

Made with ❤️ by Nishikanta Ray