v2.0 • Pure Canvas & 60 FPS

Snowfall for Astro.

A lightweight, performant canvas-based snowfall background animation component engineered for Astro and TypeScript. Zero dependencies.

$bun add astro-snowfall

Installation

Add the snowfall component to your Astro project with a single command.

$bun add astro-snowfall
Architecture

Zero Dependencies

Engineered with pure TypeScript and HTML5 Canvas API. No external animation engine required.

0 runtime packages
Footprint

~3kb Gzipped

Ultra-compact script size ensures zero noticeable impact on First Contentful Paint.

Minimal payload
Performance

60 FPS Hardware RAF

IntersectionObserver pauses canvas rendering when offscreen, conserving GPU and battery.

Auto-throttling
Integration

Astro Native

Compatible with Astro Island architecture, SSG, SSR, and ClientRouter View Transitions.

ViewTransitions safe

Engineered for Elegance.

Designed from the canvas up with attention to every frame, pixel, and byte.

60 FPS

Optimized Performance

Batch rendering via requestAnimationFrame with automatic IntersectionObserver pausing to preserve mobile battery and CPU cycles.

Configurable

Fine-Grained Controls

Precision props for snowflake count, speed range, horizontal wind drift, opacity intervals, particle radii, and custom colors.

High-DPI

Retina & Responsive

Dynamic ResizeObserver automatically matches container dimensions with pixel-ratio scaling so particles remain razor-sharp on Retina screens.

Spatial

3D Tumbling Physics

Optional pseudo-3D transformation matrices simulate realistic leaf and crystal tumbling along pitch and roll rotation axes.

TypeScript

Strict Type Safety

100% typed with exported interfaces. Complete IDE auto-completion and compile-time validation for all configuration options.

Zero Bloat

Astro Island Compatible

Engineered to blend with Astro's island architecture. Zero heavy JavaScript hydration cost when rendered statically.

Usage

Drop into any Astro page or layout. Works out of the box with zero configuration.

Pattern 01

Container Bound Snowfall

By default, the canvas automatically attaches to and resizes with its parent container. Perfect for hero banners, cards, or festive promotional callouts.

  • Auto-sizes via ResizeObserver
  • Parent needs relative positioning
Interactive Preview
src/components/FestiveBanner.astro
---
import Snowfall from "astro-snowfall";
---

<div class="relative w-full h-80 rounded-2xl overflow-hidden border border-white/10 bg-black">
  <Snowfall snowflakeCount={60} speed={[0.8, 1.8]} />
  
  <div class="relative z-10 flex h-full items-center justify-center">
    <h2 class="text-2xl font-bold text-white">Container Bound</h2>
  </div>
</div>
Pattern 02

Global Viewport Background

Fix the canvas across your layout so snow gently falls as visitors scroll through pages. Non-blocking with pointer-events disabled by design.

  • Non-interfering clicks (pointer-events-none)
  • Seamless multi-page transitions
src/layouts/Layout.astro
---
import Snowfall from "astro-snowfall";
---

<!-- Fixed background across the entire viewport -->
<div class="fixed inset-0 z-0 pointer-events-none">
  <Snowfall 
    color="#ffffff"
    snowflakeCount={120} 
    speed={[0.5, 2.0]}
    wind={[-0.3, 0.6]}
  />
</div>

Interactive Presets

Explore different atmospheres by adjusting speed, wind, density, and 3D tumbling physics.

Gentle Flurry

Subtle

Quiet, delicate snowfall with soft drift and varied transparency.

<Snowfall
  snowflakeCount={45}
  speed={[0.5, 1.5]}
  wind={[-0.4, 0.4]}
  radius={[0.6, 2.0]}
  opacity={[0.3, 0.8]}
/>

Mountain Blizzard

Dynamic

Dense, rapid snowfall with strong directional crosswind.

<Snowfall
  snowflakeCount={110}
  speed={[3.5, 7.5]}
  wind={[-2.5, 1.5]}
  radius={[0.5, 2.5]}
/>

Tumbling Crystals

Spatial 3D

Multi-axis tumbling crystals simulating spatial orientation.

<Snowfall
  enable3DRotation={true}
  rotationSpeed={[-3, 3]}
  snowflakeCount={65}
  speed={[1.2, 2.8]}
/>

Props Specification

Comprehensive reference of all configurable properties accepted by the component.

PropTypeDefaultDescription
colorstring'#dee4fd'Color of snowflakes. Any valid CSS color value (hex, rgb, hsl).
snowflakeCountnumber150Total number of snowflake particles simultaneously rendered.
radius[number, number][0.5, 3.0]Minimum and maximum snowflake radius in pixels.
speed[number, number][1.0, 3.0]Vertical falling speed range in pixels per frame.
wind[number, number][-0.5, 2.0]Horizontal drift velocity range (negative = left, positive = right).
opacity[number, number][1.0, 1.0]Randomized particle opacity interval (0.0 to 1.0).
enable3DRotationbooleanfalseEnables pseudo-3D perspective tumbling rotation around axes.
rotationSpeed[number, number][-1.0, 1.0]Tumbling angular velocity in degrees per frame (requires 3D enabled).
changeFrequencynumber200Frames between wind fluctuation changes for realistic turbulence.
classstringundefinedOptional custom CSS classes applied directly to the canvas element.