snowfall-canvas

SnowfallCanvas

➠ Install

``console
yarn add snowfall-canvas
`



➠ Import

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



➠ Usage

HTML: container + canvas (framework-friendly)
`html



`

CSS: make the canvas cover its container
`css
#snow-wrap {
position: fixed;
inset: 0;
width: 100%;
height: 100vh;
height: 100dvh;
}

#snow-canvas {
position: absolute;
inset: 0;
width: 100%;
height: 100%;
display: block;
}
`

JS: basic start
`typescript
import { SnowfallCanvas } from 'snowfall-canvas';

const snow = new SnowfallCanvas({
container: 'snow-wrap',
canvas: 'snow-canvas',
});

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

JS: configuration override
`typescript
import { SnowfallCanvas } from 'snowfall-canvas';

const snow = new SnowfallCanvas({
container: 'snow-wrap',
canvas: 'snow-canvas',
config: {
amount: 2000, // density relative to a base area
maxParticles: 3000, // hard particle limit
size: [0.6, 1.5], // particle size range (px)
swingSpeed: [0.2, 0.8], // horizontal swing speed
fallSpeed: [40, 80], // fall speed (px/s)
amplitude: [20, 45], // horizontal swing amplitude (px)
color: 'rgba(200,200,200,1)',
dprCap: 2, // DPR upper cap
},
});

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

Vue 3: Composition API example
`vue



`



➠ Constructor Options

| Option | Type | Required | Description |
|:------------|:------------------------------|:--------:|:----------------------------------------------------------------------------|
| container | HTMLElement \| string | ✅ | Container element (or its id) whose size drives internal canvas resizing. |
| canvas | HTMLCanvasElement \| string | ✅ | Canvas element (or its id) used for rendering. |
| config | Partial | ❌ | Configuration overrides. |




➠ Config Options

| Option | Type | Default | Description |
|:---------------|:-------------------|:---------------------|:-------------------------------------------------------------------------|
| amount | number | 5000 | Base particle density for a 1920×1080 area (scales with container size). |
| size | [number, number] | [0.5, 1.5] | Particle size range in pixels. |
| swingSpeed | [number, number] | [0.1, 1] | Horizontal sinusoid speed factor. |
| 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. |




➠ API Methods

| Method | Description |
|:-----------------------------------------------------|:----------------------------------------------------------------------------------------------------|
| new SnowfallCanvas({ container, canvas, config? }) | Creates an instance. Elements can be passed directly or by id string. |
| init() | Reads container size, resizes internal canvas buffer, and subscribes to resize + visibility events. |
| start() / stop() | Starts or stops the render loop. |
| destroy() | Stops and removes listeners/observers. |
| requestResize() | Schedules a resize on the next animation frame. Useful if you manually manage layout updates. |
| setAmount(amount) | Updates base density and re-seeds particles. |
| setMaxParticles(max) | Adjusts the upper limit and re-seeds particles. |




➠ Notes

- The library does not inject DOM or CSS. Your app controls layout and styling.
- The internal canvas buffer is resized to match the container size and current DPR (capped by dprCap).
- Density is auto-scaled by container area and DPR.
- Self-throttles: may reduce DPR and particle count if frames get long.
- Pauses when the tab is hidden and resumes on return.
- Ensure the container has a computed size (height must not be 0`) and the canvas covers it via CSS.

➠ License

SnowfallCanvas is released under MIT license