SeasonalFX - Documentation

Introduction

SeasonalFX brings beautiful seasonal effects to your web applications. Add realistic snow, confetti, falling leaves, and spring petals with just a few lines of code.

⚡ Lightning Fast

Under 5KB gzipped with 60 FPS performance

♿ Accessible

Respects prefers-reduced-motion and mobile optimization

🔧 Flexible

Works with React, Vue, Angular, or vanilla JS

🌍 SSR Safe

Compatible with Next.js, Nuxt, and Astro

Installation

Via NPM

npm install seasonalfx

Via CDN

No build tools required! Just include the script and start using it.

<!-- unpkg CDN -->
<script src="https://unpkg.com/seasonalfx@latest/dist/index.umd.min.js"></script>

<!-- jsDelivr CDN (recommended) -->
<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%;"></div>
  
  <script src="https://cdn.jsdelivr.net/npm/seasonalfx@latest/dist/index.umd.min.js"></script>
  
  <script>
    const fx = SeasonalFX.createSeasonalFX({
      target: document.getElementById('snow-container'),
      season: 'winter',
      intensity: 'moderate'
    });
    fx.start();
  </script>
</body>
</html>

Quick Start

Vanilla JavaScript (NPM)

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

Interactive Demo

❄️ Winter

Beautiful snowfall effect with realistic physics and drift.

Variants

light - Gentle snowfall with fewer particles
holiday - Standard winter snow
blizzard - Heavy snow with strong wind

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

🌸 Spring

Floating cherry blossom petals with gentle swirling motion.

Variants

sakura - Pink cherry blossom petals
softPetals - Mixed flower petals
pollen - Tiny floating particles

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

☀️ Summer

Subtle ambient effects like dust particles or fireflies.

Variants

heatHaze - Shimmering heat effect
sunDust - Floating dust particles
fireflies - Glowing fireflies

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

🍂 Autumn

Falling leaves with realistic tumbling motion.

Variants

maple - Colorful maple leaves
dryLeaves - Brown and yellow leaves
windy - Strong wind effect

fx.setSeason('autumn', {
  variant: 'maple',
  intensity: 'moderate',
});

🎉 Events

Time-boxed confetti effects for celebrations and special occasions.

Variants

newYear - Celebration confetti
celebration - Colorful confetti burst
launch - Product launch effect

fx.setSeason('event', {
  variant: 'celebration',
  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;
  
  // Effect intensity
  intensity?: 'minimal' | 'subtle' | 'moderate' | 'bold';
  
  // Performance
  maxFPS?: number;                // Default: 30
  
  // Accessibility
  disableOnMobile?: boolean;      // Default: true
  respectReducedMotion?: boolean; // Default: true
  
  // Debug mode
  debug?: boolean;                // Default: false
}

Intensity Levels

Level	Particles	Use Case
`minimal`	10-15	Very subtle background effect
`subtle`	30-40	Ambient effect (recommended)
`moderate`	60-80	Noticeable seasonal atmosphere
`bold`	100+	Prominent seasonal theme

Methods

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';
import { useRef } from '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>
  );
}

Performance

SeasonalFX is optimized for production use:

📦 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

Performance Tips

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

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

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

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)

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

SSR Support

SeasonalFX is fully SSR-safe and works with all major frameworks.

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>

Examples

Marketing Page with Confetti

const fx = SeasonalFX.createSeasonalFX({
  target: document.getElementById('hero'),
  season: 'event',
  seasonConfig: {
    event: {
      variant: 'launch',
      duration: 5000,
    }
  }
});

fx.start();

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;
}, 1000);