SeasonalOverlaysLibrary
A dependency-free JavaScript library for brief, full-viewport particle overlays — snow, fireworks, falling leaves, confetti, hearts, Pride-month rainbows, a flying cat with a rainbow trail, and your own custom icons — triggered by a click, or automatically from a seasonal calendar.
No download needed — link to it directly:
<script src="https://seasonaloverlayslibrary.stuxapis.net/seasonal-overlays-library.js"></script>Try it
Every button below is wired with nothing but a data-overlay-preset attribute — no JS was written for this demo grid.
● Single ● Multi ● Calendar ● Special — see what these mean below.
This page runs SeasonalOverlaysLibrary.auto() on load, in infinite mode — today's calendar preset, right now, running until you hit Stop or the tab is closed. Every month has a default preset (see the calendar below), so there's almost always something falling.
Preset types
The dots on each button above, and the badges below, mark which of these apply — a preset can be more than one.
A preset with one fixed look — no seasons or include to pick from. Most presets are this. You can still reskin colours, size, speed, etc. via the full options.
A composable preset built from named sub-elements you can pick and combine: leaves (via seasons) and halloween or christmas (via include). Leave the option out and you get a sensible default combination.
A preset that the default seasonal calendar resolves to for at least part of the year — what you'll get from preset: 'auto' on the matching date. auto itself is tagged here too, since it's the calendar's entry point.
Doesn't fit Single/Multi/Calendar: random isn't a look of its own — it picks a random preset and jitters its values each time. codebug is a deliberate easter egg, not a real theme. Both are opt-in only, never picked by auto or random itself.
Usage
Both wiring methods work at once — use whichever fits, or mix them.
<button data-overlay-preset="fireworks">Celebrate</button>
<button data-overlay-preset="fireworks" data-overlay-random-colors>Celebrate (random)</button>
<button data-overlay-preset="snow" data-overlay-infinite>Let it snow</button>
<button data-overlay-preset="leaves" data-overlay-seasons="spring,winter">Two seasons at once</button>
<button data-overlay-preset="halloween" data-overlay-include="pumpkins,skulls">No ghosts</button>
<img src="/assets/tile.png" data-overlay="/assets/pumpkin.png" alt="Spooktober">
<script src="https://seasonaloverlayslibrary.stuxapis.net/seasonal-overlays-library.js"></script>Any clickable element works — an <img>, a <button>, a <div>. Click delegation means it also picks up elements added to the page later.
SeasonalOverlaysLibrary.start({ preset: 'leaves' });
SeasonalOverlaysLibrary.start({ preset: 'snow', durationMs: null }); // infinite
SeasonalOverlaysLibrary.start({ imageUrl: '/assets/pumpkin.png' }); // fully custom, no preset
SeasonalOverlaysLibrary.start({ preset: 'random' }); // a surprise every time
SeasonalOverlaysLibrary.stop(); // stop an infinite run// Resolves today's date against the calendar and starts that preset.
SeasonalOverlaysLibrary.auto();
// Or let a trigger resolve it at click time:
// <button data-overlay-preset="auto">Surprise me</button>
// Replace the calendar with your own (checked in order, first match wins):
SeasonalOverlaysLibrary.calendar = [
{ startMonth: 6, startDay: 1, endMonth: 6, endDay: 30, preset: 'rainbows' },
{ startMonth: 12, startDay: 1, endMonth: 12, endDay: 31, preset: 'snow' }
];Presets
❄ glyphs, slow fall with gentle rotation.
🍁🍂🍃 glyphs, wide drift and tumbling rotation. Defaults to autumn — pass seasons to pick/combine spring, summer, autumn, winter. leavesSpring, leavesSummer, leavesAutumn and leavesWinter are each a single season on their own (all Single, and leavesAutumn also Calendar).
Repeating radial bursts of coloured sparks — an explode-and-fade, not a fall. Pass colors for your own palette, or randomColors: true for every spark to get its own random hue.
Combines pumpkins/skulls/ghosts, picked via include (default: all three) — e.g. include: ['pumpkins'] for just pumpkins.
Candy canes, snowballs and snowflakes by default, picked via include. trees 🎄 and gifts 🎁 are also available but opt-in.
A sprite (🐱 by default) flying across the screen trailing a rainbow. Bring your own art via imageUrl — see the note below.
Easter egg: the actual mojibake text produced during development by a missing charset header, plus a few classic bug values.
Picks a random preset (never codebug) and jitters its count/size/duration, occasionally swapping in randomColors too. Every trigger can land on a Single, Multi, or Calendar preset.
Default seasonal calendar
What preset: 'auto' / SeasonalOverlaysLibrary.auto() resolves to, out of the box — every month has one, so there's (almost) always something. Replace SeasonalOverlaysLibrary.calendar to define your own.
| When | Preset |
|---|---|
| Jan 1–2 | fireworks |
| Jan 3–31 | snow |
| Feb 1–14 | hearts |
| Feb 15–28 | snow |
| March | confetti |
| April | eastereggs |
| May | confetti |
| June | rainbows |
| Jul 1–5 | fireworks |
| Jul 6–31 | confetti |
| August | confetti |
| September | leaves |
| Oct 1–24 | pumpkins |
| Oct 25–31 | skullsghosts |
| November | leaves |
| December | snow |
Full options reference
Passed to SeasonalOverlaysLibrary.start(options), or set as a preset default.
| Option | What it does |
|---|---|
| preset | Name of a built-in preset, or 'auto' to resolve today's date against the calendar. |
| imageUrl | Single custom icon image URL (shorthand for icons: [imageUrl]). |
| icons | Array of image URLs; each particle picks one at random. |
| content | Array of text glyphs (e.g. emoji); each particle picks one at random. Always wins over seasons or include if set explicitly. |
| seasons | leaves only: which season(s) to combine into content — any of spring, summer, autumn, winter. |
| include | halloween or christmas only: which element(s) to combine into content. halloween: pumpkins, skulls, ghosts. christmas: candyCanes, snowballs, snowflakes, trees, gifts. |
| colors | CSS colors for plain-shape particles, and the text colour for non-emoji glyphs. |
| randomColors | true = every particle gets its own random hue instead of picking from colors. |
| shape | circle | square — used when no icons/content given. |
| behavior | fall (default) | burst (radial explosion, repeats) | fly (crosses the screen, optional trail). |
| count | Particles per fall batch, per firework burst, or flying sprites. |
| minSize / maxSize | Particle size in px. |
| minDuration / maxDuration | Seconds per particle (fall/fly), or per burst. |
| drift | Max horizontal drift in vw over the fall (fall only). |
| rotate | Whether particles spin as they fall (fall only). |
| burstIntervalMs | Gap between fireworks bursts (burst only, default 900). |
| trail / trailColors | Whether a fly particle leaves a fading trail, and its colours (fly only). |
| zIndex | Stacking order. Default 9999. |
| durationMs | How long the effect runs before auto-cleanup. Default 2200. Pass null for infinite. |
A note on "nyancat"
The actual Nyan Cat sprite/GIF is a specific copyrighted character, not something this
library bundles. The nyancat preset gives you the mechanic
— a sprite flying across the screen trailing a rainbow — defaulting to a
🐱 emoji. Pass your own licensed art via imageUrl if you have one:
SeasonalOverlaysLibrary.start({ preset: 'nyancat', imageUrl: '/assets/your-own-sprite.gif' });