react-sparklefall/README.md

React component wrapper for SparkleFall - Beautiful falling sparkle animations

# ✨ React SparkleFall

React component wrapper for [SparkleFall](https://github.com/theresaanna/sparklefall) - Beautiful, customizable falling sparkle animations.

## 📦 Installation

```bash
npm install react-sparklefall sparklefall
# or
yarn add react-sparklefall sparklefall
```

## 🚀 Quick Start

```jsx
import { SparkleFall } from 'react-sparklefall';
import 'sparklefall/styles.css';

function App() {
  return (
    <SparkleFall>
      <h1>✨ Sparkly Content!</h1>
    </SparkleFall>
  );
}
```

## 🎨 Examples

### Basic Usage
```jsx
<SparkleFall
  sparkles={['✨', '⭐', '💫', '🌟']}
  interval={800}
  maxSparkles={50}
>
  <div>Your content here</div>
</SparkleFall>
```

### Custom Colors
```jsx
<SparkleFall
  colors={['#FFD700', '#FFA500', '#FF8C00']}
  sparkles={['●', '◆', '■', '▲']}
  minSize={8}
  maxSize={20}
>
  <div>Golden sparkles!</div>
</SparkleFall>
```

### Wind Effect
```jsx
<SparkleFall
  wind={0.5}
  spin={true}
  minDuration={3}
  maxDuration={6}
>
  <div>Windy sparkles!</div>
</SparkleFall>
```

### Controlled Animation
```jsx
import { useState } from 'react';
import { SparkleFall } from 'react-sparklefall';

function ControlledSparkles() {
  const [paused, setPaused] = useState(false);
  
  return (
    <>
      <button onClick={() => setPaused(!paused)}>
        {paused ? 'Resume' : 'Pause'}
      </button>
      
      <SparkleFall paused={paused}>
        <div>Controlled sparkles!</div>
      </SparkleFall>
    </>
  );
}
```

## 🪝 useSparkleFall Hook

For programmatic control, use the `useSparkleFall` hook:

```jsx
import { useSparkleFall } from 'react-sparklefall';

function SparkleControls() {
  const { start, stop, burst, clear, isRunning } = useSparkleFall({
    container: document.body,
    sparkles: ['🎉', '🎊', '✨'],
    autoStart: false
  });
  
  return (
    <div>
      <button onClick={start}>Start</button>
      <button onClick={stop}>Stop</button>
      <button onClick={() => burst(20)}>Burst!</button>
      <button onClick={clear}>Clear</button>
      <p>Status: {isRunning ? 'Running' : 'Stopped'}</p>
    </div>
  );
}
```

## 📋 Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | - | Content to render inside the sparkle container |
| `className` | `string` | `''` | CSS class for the container |
| `style` | `CSSProperties` | `{}` | Inline styles for the container |
| `sparkles` | `string[]` | `['✨', '⭐', '💫', '🌟']` | Array of sparkle characters |
| `colors` | `string[] \| null` | `null` | Custom colors (null for emoji colors) |
| `interval` | `number` | `800` | Time between new sparkles (ms) |
| `minSize` | `number` | `10` | Minimum sparkle size (px) |
| `maxSize` | `number` | `30` | Maximum sparkle size (px) |
| `minDuration` | `number` | `2` | Minimum fall duration (seconds) |
| `maxDuration` | `number` | `5` | Maximum fall duration (seconds) |
| `wind` | `number` | `0` | Wind effect (-1 to 1) |
| `spin` | `boolean` | `true` | Enable rotation |
| `maxSparkles` | `number` | `50` | Max sparkles on screen |
| `autoStart` | `boolean` | `true` | Start automatically |
| `zIndex` | `number` | `9999` | Z-index of sparkle container |
| `paused` | `boolean` | `false` | Pause/resume sparkles |
| `onStart` | `() => void` | - | Callback when sparkles start |
| `onStop` | `() => void` | - | Callback when sparkles stop |

## 🎯 Use Cases

### Hero Section
```jsx
<SparkleFall
  className="hero-sparkles"
  style={{ minHeight: '100vh' }}
  maxSparkles={100}
>
  <HeroContent />
</SparkleFall>
```

### Button Click Effect
```jsx
function SparkleButton() {
  const [showSparkles, setShowSparkles] = useState(false);
  
  const handleClick = () => {
    setShowSparkles(true);
    setTimeout(() => setShowSparkles(false), 3000);
  };
  
  return (
    <button onClick={handleClick} style={{ position: 'relative' }}>
      Click Me!
      {showSparkles && (
        <SparkleFall
          style={{ 
            position: 'absolute',
            inset: 0,
            pointerEvents: 'none'
          }}
          maxSparkles={30}
        />
      )}
    </button>
  );
}
```

### Celebration Mode
```jsx
function CelebrationMode({ celebrating }) {
  if (!celebrating) return null;
  
  return (
    <SparkleFall
      sparkles={['🎉', '🎊', '🎈', '🎆', '✨']}
      interval={200}
      maxSparkles={100}
      style={{
        position: 'fixed',
        inset: 0,
        pointerEvents: 'none',
        zIndex: 10000
      }}
    />
  );
}
```

## 🔧 TypeScript Support

Full TypeScript support is included:

```tsx
import { SparkleFall, SparkleFallProps } from 'react-sparklefall';

const config: SparkleFallProps = {
  sparkles: ['✨'],
  wind: 0.5,
  maxSparkles: 100
};

<SparkleFall {...config}>
  <YourComponent />
</SparkleFall>
```

## 📝 License

MIT

## 🔗 Links

- [SparkleFall Core Library](https://github.com/theresaanna/sparklefall)
- [Live Demo](https://theresasumma.com/sparklefall)
- [NPM Package](https://www.npmjs.com/package/react-sparklefall)

---

Made with ✨ by [Theresa Summa](https://github.com/theresaanna)