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

npm install frost-react

Quick Start

import { Snowfall } from "frost-react";

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

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

Basic Usage

import { Snowfall } from "frost-react";

<Snowfall />;

Custom Configuration

import { Snowfall } from "frost-react";

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

Conditional Rendering

import { Snowfall } from "frost-react";

<Snowfall enabled={isWinter} />;

Manual CSS Import

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

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:

<Snowfall useMobileDetection={false} />

Or explicitly set the flake count:

<Snowfall flakeCount={50} /> // 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

Storybook

This library includes Storybook for visual testing and documentation:

# 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