Celebrations are their own package - domma-celebrate - so they can be used on a site with no Domma in it. Domma ships the build at dist/celebrate/ and the layout system drives it for you.

Quick Start

The layout system detects the current date and offers the toggle only during a celebration period. Nothing else to write:

<!-- Include Domma -->
<script src="dist/domma.min.js"></script>

<!-- Include Layout System (handles celebrations automatically) -->
<script type="module" src="layouts/js/layout.js"></script>

Manual Control

For testing or manual control, drive an instance yourself:

import { Celebrations } from './dist/celebrate/domma-celebrate.esm.js';

const celebrations = new Celebrations({
  theme: 'christmas',     // or 'auto' for date detection
  intensity: 'medium',    // 'light', 'medium', or 'heavy'
  enabled: true
});

// Returns false when there is nothing to show - no celebration in season,
// or a visitor who has asked for reduced motion. It never throws.
await celebrations.init();

// Change theme dynamically
await celebrations.setTheme('halloween');

// Change intensity
celebrations.setIntensity('heavy');

// Pause/resume
celebrations.pause();
celebrations.start();

// Cleanup
celebrations.destroy();

Turning individual traits off

A theme is not one switch. You may want the snow and the trees but not a steam train crossing your header:

const celebrations = new Celebrations({
  theme: 'christmas',
  traits: {
    train: false,   // no steam train
    elf: false,     // no elves
    tree: 0.5,      // half as many trees
    firework: 2     // twice as many fireworks
  }
});

// Or at runtime
celebrations.setTrait('sleigh', false);
celebrations.setTraits({ robin: false, wreath: 0.5 });

// What can this theme switch?
celebrations.getTraits();

false is off and a number is a density multiplier - 0 is off, 1 is untouched, 2 is twice as many. The panel at the top of this page is built from getTraits().

Available Themes

• christmas - Snowflakes, Santa's sleigh, reindeer, trees, wreaths, robins, toy trains, elves (Dec 1 - Jan 1)
• halloween - Pumpkins, bats, ghosts, witches, gravestones, spiders (Oct 26-31)
• valentines - Hearts, rose petals, cupid, love letters (Feb 9-14)
• guy-fawkes - Fireworks, bonfires, rockets, catherine wheels, roman candles (Nov 1-5)
• st-patricks - Shamrocks, gold coins, leprechauns, pots of gold, rainbows (Mar 12-17)
• st-andrews - Thistles, Scottish flag, bagpiper, heather (Nov 25-30)
• st-davids - Daffodils, leeks, Welsh dragon, flags (Feb 24 - Mar 1)
• st-georges - Rose petals, knights, dragons, English flag (Apr 18-23)

Intensity Levels

• light - Fewer particles, subtle effects, better performance
• medium - Balanced particle count, recommended default
• heavy - Maximum particles and decorations, spectacular display

Using it without Domma

The same package works on any site, from a single script tag:

<script src="domma-celebrate.min.js" data-celebrate></script>

That mounts the canvas and a control disc of its own, and remembers whether the visitor turned it off. See npm install domma-celebrate.

Automatic Detection

When theme is set to 'auto', the system automatically:

• Detects the current date
• Checks if any celebration is active
• Activates the appropriate theme
• Returns null if no celebration is currently active