frost-react

A lightweight, accessible, and customizable animated snowfall effect for React applications.

Features

- ❄️ Beautiful animated snowfall effect
- 📱 Mobile-optimized (automatically reduces flakes on mobile devices)
- ♿ Accessible (respects prefers-reduced-motion)
- 🎨 Highly customizable (speed, size, opacity, wind, color, and more)
- 🚀 Zero runtime dependencies (except React)
- 📦 Works with ESM and CommonJS
- 🔒 Type-safe with full TypeScript support
- 🎯 SSR-safe (works with Next.js, Remix, etc.)

Installation

``bash
npm install frost-react
`

Quick Start

`tsx
import { Snowfall } from "frost-react";

function App() {
return (



);
}
`

Props API

| Prop | Type | Default | Description |
| -------------------- | ---------------------------- | ------------------------------ | -------------------------------------- |
| enabled | boolean | true | Enable/disable the snowfall effect |
| flakeCount | number | 70 (desktop) / 35 (mobile) | Number of snowflakes to render |
| snowflakeCharacter | string | "❄️" | Character/emoji to use for snowflakes |
| speed | number \| [number, number] | [6, 12] | Animation speed (higher = faster) |
| size | number \| [number, number] | [12, 28] | Size range in pixels |
| opacity | number \| [number, number] | [0.5, 0.9] | Opacity range (0-1) |
| wind | number \| [number, number] | [-20, 20] | Horizontal drift range in pixels |
| color | string | "#ffffff" | Snowflake color |
| zIndex | number | 50 | CSS z-index value |
| style | React.CSSProperties | - | Additional inline styles for container |
| className | string | - | Additional CSS class for container |
| useMobileDetection | boolean | true | Automatically reduce flakes on mobile |

Examples

$3

`tsx
import { Snowfall } from "frost-react";

;
`

$3

`tsx
import { Snowfall } from "frost-react";

flakeCount={100}
speed={[8, 15]}
size={[10, 25]}
color="#e3f2fd"
wind={[-30, 30]}
/>;
`

$3

`tsx
import { Snowfall } from "frost-react";

;
`

$3

If you prefer to import CSS manually instead of automatic injection:

`tsx
import "frost-react/style";
import { Snowfall } from "frost-react";
`

Mobile Optimization

By default, the library automatically detects mobile devices and reduces the number of flakes from 70 to 35 for better performance. You can disable this behavior:

`tsx

`

Or explicitly set the flake count:

`tsx
// Overrides mobile detection
`

Accessibility

The component automatically:

- Sets aria-hidden="true" to avoid screen reader interference
- Respects prefers-reduced-motion media query (disables animation)
- Uses pointer-events: none to avoid blocking user interactions

Browser Support

- Modern browsers (Chrome, Firefox, Safari, Edge)
- Supports CSS custom properties (CSS variables)
- Gracefully degrades on older browsers

Development

$3

This library includes Storybook for visual testing and documentation:

`bash


Install dependencies

npm install

Start Storybook

npm run storybook

Build Storybook for deployment

npm run build-storybook
`

Storybook will open at http://localhost:6006` and provides:

- Interactive component playground
- All prop variations and examples
- Visual testing environment
- Component documentation

License

MIT