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)

Note: During Hacktoberfest 2025, the themes branch is the default branch. All theme contributions should be made to this branch.

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. Also check out our amazing contributors in CONTRIBUTORS.md.

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