# React Snowfall Effect

Create stunning, customizable snowfall animations for your React applications with ease. Perfect for winter themes, Christmas websites, or any application that needs beautiful falling particle effects.

## Features

- 🎨 **Highly Customizable**: Control every aspect of the snowfall effect
- ⚡ **Performance Optimized**: Smooth animations with configurable FPS
- 📱 **Responsive**: Automatically adapts to screen size changes
- 🎯 **Interactive**: Mouse-following snowflakes and interactive effects
- 🖼️ **Custom Images**: Use your own images as snowflakes
- 🎭 **Multiple Shapes**: Built-in circle, star, and dot shapes
- ❄️ **Realistic Physics**: Gravity, wind, bounce, and melting effects
- 📦 **TypeScript Ready**: Full TypeScript support with type definitions

## Installation

```bash
npm install @namnguyenthanhwork/react-snowfall-effect
```

## Quick Start

```tsx
import React from 'react';
import { Snowfall } from '@namnguyenthanhwork/react-snowfall-effect';

function App() {
  return (
    <div>
      <Snowfall />
      {/* Your app content */}
    </div>
  );
}

export default App;
```

## Basic Usage

```tsx
import { Snowfall } from '@namnguyenthanhwork/react-snowfall-effect'

// Simple snowfall
<Snowfall />

// Customized snowfall
<Snowfall
  snowflakeCount={100}
  colors={['#ffffff', '#e6f3ff', '#b3d9ff']}
  wind={{ min: -1, max: 1 }}
  speed={{ min: 0.5, max: 2 }}
  size={{ min: 5, max: 25 }}
/>
```

## Advanced Examples

### Interactive Snowfall

```tsx
<Snowfall
  followMouse={true}
  snowflakeCount={75}
  fadeEdges={true}
  gravity={0.8}
/>
```

### Christmas Theme

```tsx
<Snowfall
  colors={['#ffffff', '#ff6b6b', '#4ecdc4', '#ffe66d']}
  snowflakeShape='star'
  snowflakeCount={60}
  wind={{ min: -0.8, max: 0.8 }}
  accumulate={true}
/>
```

### Custom Images

```tsx
<Snowfall
  images={['/snowflake1.png', '/snowflake2.png', '/star.png']}
  snowflakeCount={40}
  size={{ min: 15, max: 35 }}
/>
```

### Bouncing Snow

```tsx
<Snowfall
  bounce={true}
  gravity={1.2}
  snowflakeCount={50}
  accumulate={true}
/>
```

## API Reference

### Props

| Prop             | Type                                                    | Default                                     | Description                              |
| ---------------- | ------------------------------------------------------- | ------------------------------------------- | ---------------------------------------- |
| `snowflakeCount` | `number`                                                | `50`                                        | Number of snowflakes                     |
| `images`         | `string[]`                                              | `[]`                                        | Array of image URLs to use as snowflakes |
| `speed`          | `{min: number, max: number}`                            | `{min: 1, max: 3}`                          | Falling speed range                      |
| `wind`           | `{min: number, max: number}`                            | `{min: -0.5, max: 0.5}`                     | Horizontal wind force                    |
| `size`           | `{min: number, max: number}`                            | `{min: 10, max: 30}`                        | Snowflake size range                     |
| `opacity`        | `{min: number, max: number}`                            | `{min: 0.1, max: 0.8}`                      | Opacity range                            |
| `rotation`       | `{enabled: boolean, speed: {min: number, max: number}}` | `{enabled: true, speed: {min: -2, max: 2}}` | Rotation settings                        |
| `colors`         | `string[]`                                              | `['#ffffff']`                               | Array of colors for snowflakes           |
| `className`      | `string`                                                | `''`                                        | Additional CSS classes                   |
| `style`          | `React.CSSProperties`                                   | `{}`                                        | Additional inline styles                 |
| `zIndex`         | `number`                                                | `1000`                                      | Z-index of the canvas                    |
| `fps`            | `number`                                                | `60`                                        | Target frames per second                 |
| `snowflakeShape` | `'circle' \| 'star' \| 'dot'`                           | `'circle'`                                  | Shape of snowflakes                      |
| `fadeEdges`      | `boolean`                                               | `true`                                      | Fade snowflakes near screen edges        |
| `followMouse`    | `boolean`                                               | `false`                                     | Make snowflakes follow mouse cursor      |
| `gravity`        | `number`                                                | `1`                                         | Gravity multiplier                       |
| `bounce`         | `boolean`                                               | `false`                                     | Enable bouncing when hitting bottom      |
| `melt`           | `boolean`                                               | `false`                                     | Enable melting effect near bottom        |
| `accumulate`     | `boolean`                                               | `false`                                     | Enable snow accumulation at bottom       |

## Performance Tips

1. **Adjust `snowflakeCount`**: Reduce for better performance on slower devices
2. **Lower `fps`**: Use 30fps instead of 60fps for mobile devices
3. **Disable expensive effects**: Turn off `followMouse`, `bounce`, or `accumulate` if not needed
4. **Use smaller images**: Optimize custom snowflake images for web

## Browser Support

- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+

## License

MIT © [Thành Nam Nguyễn](https://github.com/namnguyenthanhwork)

## Contributing

Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md) for details.

## Issues

Found a bug or have a feature request? Please open an issue on [GitHub](https://github.com/namnguyenthanhwork/react-snowfall-effect/issues).