➠ Install

yarn add snowfall-canvas

➠ Import

import { SnowfallCanvas, snowfallCanvasCssText, defaultConfig } from 'snowfall-canvas';

➠ Usage

HTML: full-screen canvas

<canvas id="snowfall-canvas"></canvas>

JS: basic start (styles auto-inserted by default)

import { SnowfallCanvas, snowfallCanvasCssText } from 'snowfall-canvas';

const canvas = document.getElementById('snowfall-canvas') as HTMLCanvasElement;
const snow = new SnowfallCanvas(canvas);

// Optional: apply default full-screen layer styles manually
const style = document.createElement('style');
style.textContent = snowfallCanvasCssText;
document.head.append(style);

snow.init();
snow.start();

JS: configuration override + manual styles (disable autoInsertStyles)

import { SnowfallCanvas } from 'snowfall-canvas';

const snow = new SnowfallCanvas('#snowfall-canvas', {
  amount: 3500,           // particle density relative to a base area
  size: [0.8, 1.6],       // particle size range (px)
  swingSpeed: [0.2, 0.8], // sinusoidal horizontal swing speed
  fallSpeed: [50, 110],   // fall speed (px/s)
  amplitude: [20, 45],    // horizontal swing amplitude (px)
  color: 'rgb(240,240,255)',
  dprCap: 1.75,           // upper DPR cap
  maxParticles: 3500,     // hard particle limit
  autoInsertStyles: false // turn off auto styles if you want custom CSS
});

// If autoInsertStyles is false, you should add your own styles:
// position: fixed/absolute; inset: 0; width: 100vw; height: 100vh;
// pointer-events: none; display: block;
snow.init();
snow.start();

➠ Options

| Option | Type | Default | Description | |:--------------:|:------------------:|:------------------:|:--------------------------------------------------------------------| | amount | number | 5000 | Base particle count for a 1920×1080 area (scales with canvas size). | | size | [number, number] | [0.5, 1.5] | Particle size range in pixels. | | swingSpeed | [number, number] | [0.1, 1] | Horizontal sinusoid speed (rad/s). | | fallSpeed | [number, number] | [40, 100] | Fall speed in px/s. | | amplitude | [number, number] | [25, 50] | Horizontal swing amplitude (px). | | color | string | "rgb(225,225,225)" | Particle color (fillStyle). | | dprCap | number | 2 | Upper bound for devicePixelRatio. | | maxParticles | number | 4000 | Hard cap for total particles. | | autoInsertStyles | boolean | true | Automatically injects default canvas styles on init(). Disable to supply custom CSS. |

➠ API Methods

| Method | Description | |-------------------------------------------|---------------------------------------------------------------------------| | new SnowfallCanvas(canvasOrId, config?) | Creates an instance. canvasOrId accepts a DOM element or a string id. | | init() | Calculates sizes and subscribes to resize and visibilitychange. | | start() / stop() | Starts or stops the render loop. | | destroy() | Stops, removes listeners, and clears references. | | resize(width, height, nextCount?) | Force new dimensions and particle count. | | setAmount(amount) | Updates base density and re-seeds particles. | | setMaxParticles(max) | Adjusts the upper limit and re-seeds particles. |

➠ Notes

• Auto-adjusts density to canvas area and current DPR.
• Self-throttles: reduces DPR and particle count if frames get long.
• Works as a full-screen layer or inside a container (ResizeObserver with window.resize fallback).
• Pauses when the tab is hidden and resumes on return.
• Colors and styles are easy to override via config.color and your canvas CSS.
• Default styles are auto-inserted. If you disable autoInsertStyles, add equivalent CSS (fixed/absolute, inset:0, 100vw/100vh, pointer-events:none, display:block) to prevent layout growth from the canvas.

➠ License

SnowfallCanvas is released under MIT license