A lightweight, performant canvas-based snowfall background animation component built with Astro and TypeScript. Ported from react-snowfall for use in Astro projects.
- ✨ Highly Configurable - Control snowflake color, size, speed, wind, and more
- 🎨 3D Rotation Effects - Enable realistic tumbling motion with 3D transformations
- 📱 Fully Responsive - Canvas automatically resizes with window/container
- ⚡ Optimized Performance - Uses
requestAnimationFrameand batch rendering - 🎯 Type-Safe - Full TypeScript support with comprehensive type definitions
- 🚀 Zero Runtime Overhead - Leverages Astro's static generation
- 🖼️ Image Support - Use custom images instead of circles (optional)
- 🎮 Programmatic Control - Play, pause, and update animations dynamically
npm install astro-snowfallnpx shadcn@latest add https://fermeridamagni.github.io/astro-snowfall/r/snowfall.json# Copy the snowfall library
cp -r src/lib/snowfall your-project/src/lib/
# Copy the Snowfall component
cp src/components/Snowfall.astro your-project/src/components/No external dependencies required!
---
import Snowfall from 'astro-snowfall';
/**
* or if you are using the library directly:
* import Snowfall from '../components/Snowfall.astro';
*/
---
<div class="container">
<Snowfall />
<main>
<h1>Your Content Here</h1>
</main>
</div>
<style>
.container {
position: relative;
min-height: 100vh;
}
</style>---
import Snowfall from 'astro-snowfall';
/**
* or if you are using the library directly:
* import Snowfall from '../components/Snowfall.astro';
*/
---
<html>
<body>
<Snowfall
class="snowfall-background"
color="#fff"
snowflakeCount={200}
enable3DRotation={true}
/>
<main>
<!-- Your content -->
</main>
</body>
</html>
<style>
.snowfall-background {
position: fixed;
inset: 0;
width: 100vw;
height: 100vh;
pointer-events: none;
z-index: 0;
}
main {
position: relative;
z-index: 1;
}
</style>All props are optional. The component uses sensible defaults for all properties.
| Prop | Type | Default | Description |
|---|---|---|---|
color |
string |
'#dee4fd' |
The color of the snowflakes (any valid CSS color) |
radius |
[number, number] |
[0.5, 3.0] |
Min and max radius of snowflakes in pixels |
opacity |
[number, number] |
[1, 1] |
Min and max opacity (0-1 range) |
| Prop | Type | Default | Description |
|---|---|---|---|
speed |
[number, number] |
[1.0, 3.0] |
Min and max vertical falling speed |
wind |
[number, number] |
[-0.5, 2.0] |
Min and max horizontal wind velocity |
rotationSpeed |
[number, number] |
[-1.0, 1.0] |
Min and max rotation speed (degrees/frame) |
changeFrequency |
number |
200 |
Frames between target speed/wind updates |
enable3DRotation |
boolean |
false |
Enable 3D tumbling rotation effect |
| Prop | Type | Default | Description |
|---|---|---|---|
snowflakeCount |
number |
150 |
Number of snowflakes to render |
| Prop | Type | Default | Description |
|---|---|---|---|
class |
string |
undefined |
CSS class name for the canvas element |
style |
string |
undefined |
Inline CSS styles for the canvas |
| Prop | Type | Default | Description |
|---|---|---|---|
images |
CanvasImageSource[] |
undefined |
Array of images to use instead of circles |
<Snowfall
color="#ffffff"
snowflakeCount={300}
speed={[0.5, 2]}
wind={[-1, 1]}
radius={[0.5, 4]}
enable3DRotation={true}
/><Snowfall
color="rgba(255, 255, 255, 0.6)"
snowflakeCount={50}
speed={[0.5, 1.5]}
wind={[0, 0.5]}
radius={[1, 2]}
/><Snowfall
color="#ff69b4"
snowflakeCount={100}
speed={[2, 5]}
wind={[-2, 2]}
radius={[1, 5]}
enable3DRotation={true}
rotationSpeed={[-5, 5]}
/><Snowfall
color="#e0f2ff"
snowflakeCount={500}
speed={[3, 6]}
wind={[-3, 3]}
radius={[0.5, 3]}
opacity={[0.4, 0.9]}
/>The snowfall animation is built with three core components:
Each snowflake is an individual entity with its own properties:
- Position (x, y coordinates)
- Velocity (speed and wind)
- Appearance (radius, opacity, rotation)
- Physics (lerping between target values)
Manages the animation lifecycle:
- Creates and maintains snowflake collection
- Runs animation loop with
requestAnimationFrame - Updates positions based on physics
- Renders to canvas with optimizations
- Provides play/pause/resize controls
Wraps everything in a user-friendly interface:
- Accepts configuration props
- Sets up canvas element
- Initializes controller on client-side
- Handles responsive resizing with
ResizeObserver - Manages cleanup on navigation
The animation uses frame-based updates for consistent behavior:
- Linear Interpolation (lerp): Snowflakes smoothly transition between random speed/wind values
- Frame Calculation: Adjusts for varying frame rates to maintain consistent motion
- Wrapping: Snowflakes wrap around screen edges for infinite effect
- 3D Rotation: Optional transformation matrices for realistic tumbling
- Batch Rendering: When using circles without 3D rotation, all snowflakes are drawn in a single
beginPath()call - Target FPS: Animation targets 60fps with frame delta calculations
- Efficient Updates: Only updates visible properties
- Canvas Clipping: Clears and redraws only changed regions
The canvas automatically adapts to its container size using ResizeObserver:
// Monitors container size changes
const resizeObserver = new ResizeObserver(() => {
canvas.width = canvas.offsetWidth;
canvas.height = canvas.offsetHeight;
snowfall.resize(canvas.width, canvas.height);
});This ensures the animation works perfectly on:
- Desktop browsers
- Mobile devices
- Responsive layouts
- Window resizing
- Orientation changes
Works in all modern browsers that support:
- HTML5 Canvas API
requestAnimationFrameResizeObserver- ES6+ JavaScript
- ✅ Chrome/Edge 90+
- ✅ Firefox 88+
- ✅ Safari 14+
- ✅ iOS Safari 14+
- ✅ Android Chrome 90+
Larger canvases require more rendering time. For full-screen effects:
- Desktop: 300-500 snowflakes work well
- Mobile: Limit to 100-200 snowflakes
Enabling 3D rotation disables batch rendering optimization. Each snowflake is drawn individually with transforms.
The animation targets 60fps but gracefully degrades on slower devices. Frame calculations ensure motion remains consistent.
Full type definitions are included:
import type {
SnowflakeProps,
SnowflakeConfig,
SnowfallCanvasConfig
} from '../lib/snowfall/types';src/
├── components/
│ └── Snowfall.astro # Main Astro component
├── lib/
│ └── snowfall/
│ ├── snowflake.ts # Individual snowflake class
│ ├── snowfall-canvas.ts # Animation controller
│ ├── types.ts # TypeScript definitions
│ ├── utils.ts # Helper functions
│ └── config.ts # Default configuration
└── pages/
└── index.astro # Demo page
This implementation is based on react-snowfall by Cahil Foley, adapted for Astro and enhanced with:
- Native TypeScript types
- Astro-specific patterns
- ResizeObserver for responsive behavior
- Enhanced 3D rotation
- Optimized rendering pipeline
MIT License - Feel free to use in your projects!
Contributions are welcome! Please feel free to submit a Pull Request.
If you encounter any issues or have questions, please open an issue on GitHub.
Built with ❤️ by @fermeridamagni