Festive.js is a tiny, zero-dependency Web SDK that adds seasonal overlays (Diwali crackers 🎆, Christmas snow ❄️, etc.) to websites.

It is designed to be minimal, lightweight, and non-intrusive — overlays should celebrate, not interfere. They must never harm the aesthetics, performance, or functionality of the host site.

This project was born at Inovus Labs — a student innovation hub where we experiment, build, and open-source our learnings.
We noticed that during festivals and events, websites often add heavy, distracting animations that ruin UX. We asked:

👉 Can we make festive websites truly festive, without compromising their design or performance?

That’s how Festive.js was started:

• A lightweight overlay SDK
• Vanilla JS, no third-party libraries, no CSS frameworks
• Subtle, configurable, celebratory effects

Now we are opening this project up for the community, starting with Hacktoberfest 2025.

• To create an open gallery of lightweight festive themes anyone can drop into their site.
• To show how community contributions can make a project vibrant.
• To give new developers a chance to contribute to a real open-source SDK.
• To demonstrate clean, non-intrusive design principles in frontend/web SDK development.

We are running this project as an Inovus Labs Hacktoberfest Initiative:

1. October 2025 (Hacktoberfest Season)

   • Kick off project as open source
   • Accept community contributions (themes + core improvements)
   • Build showcase, docs site, and demo platform

2. End of October

   • Finalize and merge contributions
   • Publish v1.0.0 with a stable SDK + official theme gallery

3. Beyond Hacktoberfest

   • Add more seasonal/cultural themes
   • Expand SDK capabilities (mount targets, presets, mobile-first optimizations)
   • Build peripheral platforms (bookmarklets, theme generator, gallery site)

You can contribute to Festive.js in two ways:

• Add a new festive theme (Diwali, Halloween, Independence Day, New Year, Easter, local cultural festivals, etc.)
• Keep it lightweight, minimal, and non-intrusive
• Each theme has:
  • index.js → theme implementation with metadata, params, auto-trigger rules, and effect implementation

• Improve SDK internals (performance optimizations, cleanup improvements)
• Add new capabilities:
  • Mount overlays inside a target container
  • Theme parameter presets
  • Mobile-friendly rendering tweaks
• Build peripheral platforms:
  • Bookmarklet for testing on any site
  • Docs & showcase website improvements
  • Playground for parameter tweaking

• 📦 Drop-in script via CDN
• 🎨 Themes auto-activate by date or can be forced
• ⚡ Lightweight — no libraries, no CSS frameworks
• 🖼️ Non-intrusive overlays (no DOM breakage)
• 🔧 Configurable params per theme
• 📅 Auto-trigger (e.g. Diwali Oct 20–Nov 20)

To quickly add Festive.js to your site, include the script from the CDN and initialize:

<script src="https://unpkg.com/festive-js"></script>
<script>
  Festive.init(); // auto-pick theme by date
</script>

To force a specific theme (e.g. for testing), use:

Festive.init({ forceTheme: "christmas-snow" });
// or
Festive.init({ forceTheme: "snowfall" });
// or
Festive.init({ forceTheme: "santa" });

To customize parameters for a theme, pass them in the themes option:

Festive.init({
  forceTheme: "snowfall",
  themes: {
    "snowfall": { 
      density: 150, 
      snowflakeChar: "✦", 
      color: "#87ceeb",
      driftRange: 30 
    }
  }
});

// Santa theme example
Festive.init({
  forceTheme: "santa",
  themes: {
    "santa": {
      santaSize: 200,
      unicycleDuration: 10,
      sledDuration: 8,
      showOverlay: true
    }
  }
});

See CONTRIBUTING.md for full guidelines.

This project is licensed under the MIT License. See LICENSE for details.