Vue Snowfall

A customizable and performant Vue 3 composable for creating beautiful snowfall effects in your web applications.

✨ Features

• 🎨 Highly Customizable - Configure speed, size, color, interval, chaos level, and more
• ⚡ Performant - Optimized with efficient DOM management, shared CSS animations, and automatic cleanup
• 🎯 Flexible - Choose any container element or use the default body
• 🔧 Easy to Use - Simple API with sensible defaults
• 📦 Lightweight - Small bundle size, no external dependencies
• 🎭 Vue 3 Compatible - Built for Vue 3 Composition API

📦 Installation

npm install vue-snowfall
# or
pnpm add vue-snowfall
# or
yarn add vue-snowfall

🚀 Quick Start

Basic Usage

import { useSnowfall } from 'vue-snowfall'
import { onMounted, onBeforeUnmount } from 'vue'

export default {
  setup() {
    const { startSnowflakes, stopSnowflakes } = useSnowfall()

    onMounted(() => {
      startSnowflakes()
    })

    onBeforeUnmount(() => {
      stopSnowflakes()
    })
  }
}

With Options

import { useSnowfall } from 'vue-snowfall'

const { startSnowflakes, stopSnowflakes } = useSnowfall({
  interval: 300,           // Create snowflake every 300ms
  minSpeed: 15,           // Minimum falling speed (seconds)
  maxSpeed: 25,           // Maximum falling speed (seconds)
  minSize: 10,            // Minimum size in pixels
  maxSize: 30,            // Maximum size in pixels
  color: '#ffffff',       // Snowflake color
  zIndex: 999,            // Z-index for snowflakes
  maxFlakes: 100,         // Maximum number of snowflakes (optional)
  chaos: 50,              // Chaos level for random movement (0-100)
  container: document.body // Container element or selector
})

startSnowflakes()

📖 API Reference

useSnowfall(options?)

Creates a snowfall effect instance.

Parameters

| Option | Type | Default | Description | |--------|------|---------|-------------| | container | HTMLElement \| string | document.body | Container element or CSS selector | | interval | number | 500 | Interval between creating snowflakes (ms) | | minSpeed | number | 20 | Minimum falling speed (seconds) | | maxSpeed | number | 30 | Maximum falling speed (seconds) | | minSize | number | 10 | Minimum snowflake size in pixels | | maxSize | number | 30 | Maximum snowflake size in pixels | | color | string | '#fff' | Snowflake color (hex, rgb, etc.) | | zIndex | number | 999 | Z-index for snowflakes | | maxFlakes | number \| null | null | Maximum number of snowflakes (null = unlimited) | | chaos | number | 50 | Chaos level for random movement (0-100, higher = more chaotic) |

Returns

An object with the following methods:

• startSnowflakes() - Start the snowfall animation
• stopSnowflakes() - Stop the animation and remove all snowflakes

🎨 Examples

Custom Container

import { useSnowfall } from 'vue-snowfall'

const { startSnowflakes, stopSnowflakes } = useSnowfall({
  container: '#snow-container', // CSS selector
  // or
  container: document.querySelector('.my-container') // Element
})

startSnowflakes()

Fast Snowfall

const { startSnowflakes } = useSnowfall({
  interval: 200,
  minSpeed: 5,
  maxSpeed: 10
})

startSnowflakes()

Slow, Large Snowflakes

const { startSnowflakes } = useSnowfall({
  interval: 1000,
  minSpeed: 30,
  maxSpeed: 50,
  minSize: 20,
  maxSize: 50
})

startSnowflakes()

Colored Snowflakes

const { startSnowflakes } = useSnowfall({
  color: '#ff6b9d' // Pink snowflakes!
})

startSnowflakes()

Chaotic Movement

const { startSnowflakes } = useSnowfall({
  chaos: 80 // Higher chaos = more random horizontal movement (0-100)
})

startSnowflakes()

Performance Optimization

const { startSnowflakes } = useSnowfall({
  maxFlakes: 50, // Limit to 50 snowflakes for better performance
  interval: 400
})

startSnowflakes()

🔧 Advanced Usage

Dynamic Configuration

import { ref, watch } from 'vue'
import { useSnowfall } from 'vue-snowfall'

const speed = ref(20)
let snowfall = null

watch(speed, (newSpeed) => {
  if (snowfall) {
    snowfall.stopSnowflakes()
  }
  snowfall = useSnowfall({ minSpeed: newSpeed, maxSpeed: newSpeed + 10 })
  snowfall.startSnowflakes()
}, { immediate: true })

Multiple Instances

const snowfall1 = useSnowfall({ container: '#container1' })
const snowfall2 = useSnowfall({ container: '#container2', color: '#ff0000' })

snowfall1.startSnowflakes()
snowfall2.startSnowflakes()

🎯 Performance Tips

1. Use maxFlakes to limit the number of snowflakes for better performance on low-end devices
2. Increase interval to create snowflakes less frequently
3. Use a specific container instead of document.body when possible
4. Stop snowfall when not visible (e.g., when component is unmounted or tab is hidden)
5. Optimized rendering - The library uses a single shared CSS animation with CSS variables for optimal performance
6. Automatic cleanup - Snowflakes are automatically removed when animation completes, reducing memory usage

🐛 Troubleshooting

Snowflakes not appearing

• Make sure the container has a defined height
• Check that the container is visible (not display: none)
• Verify that startSnowflakes() is called after the container is mounted

Performance issues

• Reduce maxFlakes or increase interval
• Use a smaller container instead of the entire body
• Consider stopping snowfall when the page is not visible

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

Made with ❄️ by Erlan Kaparov