🎉 Festive Effects

Beautiful, performant festival animations for React.

🎨 Live Demo | 📦 npm

✨ Features

• 🎄 12 Festival Effects - Christmas, New Year, Valentine, Easter, Halloween, Thanksgiving, Diwali, Chinese New Year, Holi, Eid, St. Patrick's, Independence Day
• ⚡ 60fps Performance - Smooth, GPU-accelerated animations
• 📦 Lightweight - Tree-shakeable, minimal bundle impact
• ♿ Accessible - Respects prefers-reduced-motion
• 🔧 Customizable - Intensity, duration, colors & more
• 💪 TypeScript - Full type safety out of the box

📦 Installation

npm install festive-effects
# or
yarn add festive-effects
# or
pnpm add festive-effects

🚀 Quick Start

import { FestiveEffects } from 'festive-effects';

function App() {
  return (
    <div>
      <h1>Happy Holidays!</h1>
      <FestiveEffects festival="christmas" />
    </div>
  );
}

🎨 Available Festivals

| Festival | Prop Value | Effect | Particles | |----------|------------|--------|----------| | 🎄 Christmas | christmas | Falling snowflakes | snowflake, gift, star | | 🎆 New Year | newyear | Fireworks & confetti | | 💝 Valentine | valentine | Floating hearts | | 🐰 Easter | easter | Eggs & flowers | | 🎃 Halloween | halloween | Bats & pumpkins | | 🍂 Thanksgiving | thanksgiving | Autumn leaves | | 🪔 Diwali | diwali | Diyas & sparkles | | 🏮 Chinese New Year | chinesenewyear | Lanterns & dragons | | 🎨 Holi | holi | Color splashes | | 🌙 Eid | eid | Moons & stars | | ☘️ St. Patrick's | stpatricks | Shamrocks | | 🎇 Independence Day | independence | Patriotic fireworks |

⚙️ Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | festival | FestivalType | required | The festival effect to display | | intensity | 'low' \| 'medium' \| 'high' | 'medium' | Particle density | | duration | number | undefined | Auto-stop after ms (infinite if not set) | | zIndex | number | 9999 | CSS z-index of overlay | | respectReducedMotion | boolean | true | Honor user's motion preferences | | colors | string[] | festival default | Custom color palette | | particleTypes | ParticleType[] | festival default | Override which particles to show |

📖 Examples

Basic Usage

<FestiveEffects festival="christmas" />

With Intensity

<FestiveEffects 
  festival="newyear" 
  intensity="high" 
/>

Auto-stop After 10 Seconds

<FestiveEffects 
  festival="valentine" 
  duration={10000} 
/>

Custom Colors

<FestiveEffects 
  festival="independence" 
  colors={['#FF0000', '#FFFFFF', '#0000FF']} 
/>

Filter Particle Types (New in 1.1.0)

// Only snowflakes
<FestiveEffects 
  festival="christmas" 
  particleTypes={['snowflake']} 
/>

// Snowflakes + gifts (no stars)
<FestiveEffects 
  festival="christmas" 
  particleTypes={['snowflake', 'gift']} 
/>

Conditional Rendering

function App() {
  const [showEffects, setShowEffects] = useState(false);

  return (
    <>
      <button onClick={() => setShowEffects(true)}>
        Celebrate! 🎉
      </button>
      {showEffects && (
        <FestiveEffects 
          festival="diwali" 
          duration={5000}
        />
      )}
    </>
  );
}

🎯 TypeScript

Full TypeScript support with exported types:

import { 
  FestiveEffects,
  type FestivalType,
  type IntensityLevel,
  type FestiveEffectsProps 
} from 'festive-effects';

const festival: FestivalType = 'christmas';
const intensity: IntensityLevel = 'medium';

♿ Accessibility

By default, FestiveEffects respects the user's prefers-reduced-motion setting. When enabled, no animations will render.

To override this behavior:

<FestiveEffects 
  festival="christmas" 
  respectReducedMotion={false} 
/>

📄 License

MIT © Harshit

Made with 💜 for developers who celebrate