FestiveLayer

Developer Documentation

Integrate FestiveLayer into any web application or CMS in under 60 seconds. Zero dependencies, strict Shadow DOM containment, and full API control.

1 · 60-Second Quick-Start

Paste this single script tag right before the closing </body> tag on any web page:

Quick-Start HTML
<script src="https://cdn.example.com/v1/festive.js"
        data-festival="auto" async></script>

2 · Declarative Configuration (data- Attributes)

Configure the engine declaratively directly on the script element without writing JavaScript:

AttributeTypeDefaultDescription
data-festival string "auto" Festival ID (e.g. "christmas", "new-year", "sinhala-tamil-new-year") or "auto" to follow the calendar. Set to "none" to disable.
data-intensity string | number "medium" Particle density multiplier: "low" (0.5x), "medium" (1.0x), "high" (1.6x), or numeric float.
data-z number 999999 CSS z-index applied to the fixed canvas overlay.
data-base URL (Auto) Custom CDN directory path where lazy-loaded festival pack JS files reside.
data-key string "" Cryptographically signed domain license token.
data-debug string "0" Set to "1" to render live FPS, frame execution time, and active particle counters.

3 · JavaScript API (window.Festive)

Control the animation dynamically from your own client code:

Festive.start(id?)

Mounts the canvas overlay and begins the animation loop for the given festival ID (or active calendar festival).

Festive.stop()

Halts the animation loop, removes all listeners, and cleanly detaches the overlay from the DOM.

Festive.setFestival(id)

Switches the active pack dynamically (e.g. Festive.setFestival('new-year')) without unmounting.

Festive.setIntensity(level)

Adjusts visual particle density on the fly ('low', 'medium', 'high', or float).

Festive.trigger(action, x?, y?)

Dispatches custom festival events (e.g. 'santa', 'launch', 'lamp', 'kolam', 'firecracker').

4 · Platform Installation Guides

Shopify

In your Shopify Admin, go to Online Store > Themes > Edit code. Open layout/theme.liquid, find </body>, and paste before it:

theme.liquid
<!-- Paste immediately above </body> in layout/theme.liquid -->
<script src="https://cdn.example.com/v1/festive.js"
        data-festival="auto"
        data-intensity="medium"
        async></script>

WordPress

Use our standalone single-file plugin or paste this hook into your active theme's functions.php:

functions.php
// Add to functions.php or active child theme
add_action('wp_footer', function() {
    echo '<script src="https://cdn.example.com/v1/festive.js" data-festival="auto" data-intensity="medium" async></script>';
});

React & Next.js

Use Next.js Script component with strategy="lazyOnload" in your root layout:

app/layout.tsx
// Next.js App Router (app/layout.tsx)
import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://cdn.example.com/v1/festive.js"
          strategy="lazyOnload"
          data-festival="auto"
          data-intensity="medium"
        />
      </body>
    </html>
  );
}

Google Tag Manager (GTM)

Create a Custom HTML Tag with a trigger set to Window Loaded:

GTM Custom HTML
<!-- Google Tag Manager: Custom HTML Tag triggered on Window Loaded -->
<script src="https://cdn.example.com/v1/festive.js"
        data-festival="auto"
        data-intensity="medium"
        async></script>

Wix & Squarespace

Navigate to Settings > Custom Code / Code Injection, select Body - End, and paste the standard quick-start snippet.