✨ React SparkleFall

React component wrapper for SparkleFall - Beautiful, customizable falling sparkle animations.

📦 Installation

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

🚀 Quick Start

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

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

🎨 Examples

Basic Usage

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

Custom Colors

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

Wind Effect

<SparkleFall
  wind={0.5}
  spin={true}
  minDuration={3}
  maxDuration={6}
>
  <div>Windy sparkles!</div>
</SparkleFall>

Controlled Animation

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:

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

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

Button Click Effect

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

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:

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
• Live Demo
• NPM Package

Made with ✨ by Theresa Summa