🎊 rn-confetti-love

Beautiful animated confetti effects for React Native. While designed with love-themed apps in mind, it is fully customizable for any celebration!

✨ Features

• 🎨 Full Customization: Control colors, emojis, texts, images, and shapes
• 💖 Love Presets: Built-in specialized presets for romantic effects
• ⬆️ Direction Control: Top-to-bottom (fall) or bottom-to-top (rise) animations
• 🎭 Custom Content: Mix emojis, text, avatars, and custom views
• ⚡ Performant: Built with React Native Reanimated for 60fps animations
• 📱 Responsive: Auto-adjusts to screen dimensions

📦 Installation

npm install rn-confetti-love
# or
yarn add rn-confetti-love

Peer Dependencies

Make sure you have the following packages installed:

npm install react-native-reanimated expo-image

Note: expo-image is optional and only required if you want to display avatar images/custom images in the confetti.

🚀 Usage

LoveConfetti Component

A simplified wrapper component that uses the default love-themed configuration.

import { LoveConfetti } from 'rn-confetti-love';

<LoveConfetti
  isVisible={showConfetti}
  onComplete={() => setShowConfetti(false)}
/>

Note: LoveConfetti is primarily for backward compatibility. For new implementations, we recommend using the main Confetti component.

Confetti Component (Customizable)

For full control, use the Confetti component with the config prop.

import { Confetti } from 'rn-confetti-love';

<Confetti
  isVisible={true}
  config={{
    emojis: ['🎉', '🥳'],
    colors: ['#FFD700', '#FF0000']
  }}
  onComplete={onDone}
/>

🛠️ Advanced Customization

Pass a config object to customize every aspect of the confetti.

Custom Emojis & Colors

Create a birthday or celebration theme:

<Confetti
  isVisible={true}
  pieceCount={100}
  config={{
    emojis: ['🎉', '🎂', '🥳', '🎈'],
    colors: ['#FFD700', '#FF6347', '#4169E1', '#32CD32'],
    distribution: { emojis: 1 } // 100% emojis
  }}
  onComplete={onDone}
/>

Custom Text/Names

Display custom messages or names:

<Confetti
  isVisible={true}
  config={{
    texts: ['Winner!', 'Level Up', '+100 XP'],
    colors: ['#FFD700'], // Gold text
    distribution: { texts: 1 }
  }}
  onComplete={onDone}
/>

Custom Images & Avatars

Mix images with other confetti pieces:

<Confetti
  isVisible={true}
  config={{
    images: ['https://example.com/avatar1.png', 'https://example.com/avatar2.png'],
    emojis: ['🌟', '✨'],
    distribution: { images: 0.3, emojis: 0.7 } // 30% images, 70% sparkles
  }}
  onComplete={onDone}
/>

Fine-Tuning Animations

Control speed, sway, and rotation:

<Confetti
  isVisible={true}
  config={{
    animation: {
      minDuration: 4000,    // Slower animation
      maxDuration: 6000,
      minSway: 50,          // Wider sway
      maxSway: 100,
      maxRotation: 720,     // More spinning
    }
  }}
  onComplete={onDone}
/>

🔄 Direction Options

Top to Bottom (direction="top-to-bottom")

Classic confetti falling from the sky.

Bottom to Top (direction="bottom-to-top")

Hearts rising up like floating balloons - perfect for "send love" interactions!

🎯 Use Cases

• 💑 Anniversary celebrations
• 💝 Valentine's Day features
• 💌 Sending love messages
• 🎉 Relationship milestones
• 💒 Wedding apps
• 💕 Romantic date apps

📖 API Reference

Confetti Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | isVisible | boolean | required | Controls visibility of the confetti | | config | ConfettiConfig | undefined | Configuration object for full customization | | direction | 'top-to-bottom' \| 'bottom-to-top' | 'top-to-bottom' | Animation direction | | pieceCount | number | 55 | Number of confetti pieces | | onComplete | () => void | undefined | Callback when all pieces finish animating |

ConfettiConfig Object

The config prop accepts an object with the following optional keys:

| Key | Type | Description | |-----|------|-------------| | emojis | string[] | Array of emoji characters to use | | texts | string[] | Array of text strings to display | | initials | string[] | Array of characters for initial circles | | images | string[] | Array of image URIs | | colors | string[] | Array of colors for text and shapes | | distribution | ContentDistribution | Object defining % of each content type | | animation | AnimationConfig | Timing and movement settings | | sizes | SizeConfig | Size boundaries for different pieces | | styles | ConfettiStyles | Custom RN styles for piece components | | customContent | ConfettiContentItem[] | Array for fully custom weighted content |

AnimationConfig

| Key | Default | Description | |-----|---------|-------------| | minDuration | 3000 | Minimum animation duration (ms) | | maxDuration | 5000 | Maximum animation duration (ms) | | maxDelay | 1500 | Max start delay for separate pieces (ms) | | minSway | 30 | Minimum horizontal sway (px) | | maxSway | 90 | Maximum horizontal sway (px) | | maxRotation | 360 | Max rotation in degrees |

Legacy Props (Deprecated)

These props are still supported but mapped internally to the new config system.

• variant: Use config presets instead
• partner1Name/partner2Name: Use config.texts
• partner1Avatar/partner2Avatar: Use config.images

🧩 Types

export interface ConfettiConfig {
  emojis?: string[];
  texts?: string[];
  initials?: string[];
  images?: string[];
  colors?: string[];
  distribution?: {
    emojis?: number;   // 0-1
    texts?: number;    // 0-1
    initials?: number; // 0-1
    images?: number;   // 0-1
  };
  // ... and more
}

📄 License

MIT

Made with 💖