rn-confetti-love 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,232 @@
+# 🎊 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!
+
+![npm](https://img.shields.io/npm/v/rn-confetti-love)
+![license](https://img.shields.io/npm/l/rn-confetti-love)
+
+## ✨ 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
+
+```bash
+npm install rn-confetti-love
+# or
+yarn add rn-confetti-love
+```
+
+### Peer Dependencies
+
+Make sure you have the following packages installed:
+
+```bash
+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.
+
+```tsx
+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.
+
+```tsx
+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:
+
+```tsx
+<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:
+
+```tsx
+<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:
+
+```tsx
+<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:
+
+```tsx
+<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
+
+```typescript
+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 💖

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "rn-confetti-love",
+  "version": "1.0.0",
+  "description": "Beautiful animated confetti effects for React Native with love-themed variants featuring hearts, names, initials, and avatars",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typescript": "tsc --noEmit"
+  },
+  "keywords": [
+    "react-native",
+    "confetti",
+    "animation",
+    "love",
+    "hearts",
+    "celebration",
+    "effects",
+    "reanimated",
+    "expo"
+  ],
+  "author": "ShanuChandi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ShanuChandi/rn-confetti-love.git"
+  },
+  "bugs": {
+    "url": "  https://github.com/ShanuChandi/rn-confetti-love/issues"
+  },
+  "homepage": "https://github.com/ShanuChandi/rn-confetti-love#readme",
+  "peerDependencies": {
+    "expo-image": ">=1.0.0",
+    "react": ">=17.0.0",
+    "react-native": ">=0.64.0",
+    "react-native-reanimated": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "expo-image": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.27",
+    "@types/react-native": "^0.72.8",
+    "typescript": "^5.0.0"
+  }
+}

package/src/Confetti.tsx

@@ -0,0 +1,667 @@
+import { Image } from 'expo-image';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { Dimensions, StyleSheet, Text, View, ImageStyle, TextStyle, ViewStyle } from 'react-native';
+import Animated, {
+  Easing,
+  useAnimatedStyle,
+  useSharedValue,
+  withDelay,
+  withTiming,
+} from 'react-native-reanimated';
+
+const { width: SCREEN_WIDTH, height: SCREEN_HEIGHT } = Dimensions.get('window');
+
+// ============================================================================
+// TYPES & INTERFACES
+// ============================================================================
+
+/** Types of confetti pieces that can be rendered */
+export type ConfettiPieceType = 'emoji' | 'text' | 'image';
+
+/** Direction for confetti animation */
+export type ConfettiDirection = 'top-to-bottom' | 'bottom-to-top';
+
+/** Animation timing configuration */
+export interface AnimationConfig {
+  /** Minimum animation duration in ms (default: 3000) */
+  minDuration?: number;
+  /** Maximum animation duration in ms (default: 5000) */
+  maxDuration?: number;
+  /** Maximum delay before piece starts animating in ms (default: 1500) */
+  maxDelay?: number;
+  /** Minimum horizontal sway amount in pixels (default: 30) */
+  minSway?: number;
+  /** Maximum horizontal sway amount in pixels (default: 90) */
+  maxSway?: number;
+  /** Sway cycle duration in ms (default: 800) */
+  swayCycleDuration?: number;
+  /** Maximum rotation in degrees (default: 360) */
+  maxRotation?: number;
+  /** Fade out starts at this percentage of duration (default: 0.7 = 70%) */
+  fadeOutStart?: number;
+}
+
+/** Size configuration for confetti pieces */
+export interface SizeConfig {
+  /** Minimum scale factor (default: 0.5) */
+  minScale?: number;
+  /** Maximum scale factor (default: 1.5) */
+  maxScale?: number;
+  /** Emoji font size (default: 28) */
+  emojiFontSize?: number;
+  /** Text font size (default: 14) */
+  textFontSize?: number;
+  /** Initial circle size (default: 36) */
+  initialCircleSize?: number;
+  /** Initial text font size (default: 18) */
+  initialFontSize?: number;
+  /** Avatar image size (default: 40) */
+  avatarSize?: number;
+}
+
+/** Custom content item for confetti */
+export interface ConfettiContentItem {
+  /** Type of content */
+  type: ConfettiPieceType;
+  /** Content value - emoji/text string or image URI */
+  value: string;
+  /** Optional weight for random selection (default: 1) */
+  weight?: number;
+  /** Optional custom color for this item */
+  color?: string;
+}
+
+/** Distribution configuration for built-in content types */
+export interface ContentDistribution {
+  /** Percentage of emoji pieces (0-1, default: 0.5) */
+  emojis?: number;
+  /** Percentage of text pieces like names (0-1, default: 0.3) */
+  texts?: number;
+  /** Percentage of initial/letter pieces (0-1, default: 0.1) */
+  initials?: number;
+  /** Percentage of image pieces (0-1, default: 0.1) */
+  images?: number;
+}
+
+/** Style customization for confetti pieces */
+export interface ConfettiStyles {
+  /** Custom emoji text style */
+  emoji?: TextStyle;
+  /** Custom text style */
+  text?: TextStyle;
+  /** Custom initial circle container style */
+  initialCircle?: ViewStyle;
+  /** Custom initial text style */
+  initialText?: TextStyle;
+  /** Custom image container style */
+  imageContainer?: ViewStyle;
+  /** Custom image style */
+  image?: ImageStyle;
+}
+
+/** Main configuration object for full customization */
+export interface ConfettiConfig {
+  // === Content Configuration ===
+  /** Array of emoji strings to use (default: heart emojis) */
+  emojis?: string[];
+  /** Array of text strings to display (e.g., names) */
+  texts?: string[];
+  /** Array of single characters/initials to display */
+  initials?: string[];
+  /** Array of image URIs to display */
+  images?: string[];
+  /** Custom content items with full control */
+  customContent?: ConfettiContentItem[];
+  /** Distribution weights for content types (ignored if customContent is provided) */
+  distribution?: ContentDistribution;
+
+  // === Color Configuration ===
+  /** Array of colors to use for text/initials (default: pink/love colors) */
+  colors?: string[];
+
+  // === Animation Configuration ===
+  /** Animation timing settings */
+  animation?: AnimationConfig;
+
+  // === Size Configuration ===
+  /** Size settings for pieces */
+  sizes?: SizeConfig;
+
+  // === Style Overrides ===
+  /** Custom styles for different piece types */
+  styles?: ConfettiStyles;
+}
+
+/** Internal confetti piece data structure */
+interface ConfettiPiece {
+  id: number;
+  type: ConfettiPieceType;
+  content: string;
+  imageUri?: string;
+  isInitial?: boolean;
+  startX: number;
+  startY: number;
+  endY: number;
+  rotation: number;
+  scale: number;
+  delay: number;
+  duration: number;
+  swayAmount: number;
+  swayCycleDuration: number;
+  color: string;
+  direction: ConfettiDirection;
+}
+
+/** Props for the main Confetti component */
+export interface ConfettiProps {
+  /** Controls visibility of the confetti */
+  isVisible: boolean;
+  /** Animation direction (default: 'top-to-bottom') */
+  direction?: ConfettiDirection;
+  /** Number of confetti pieces (default: 55) */
+  pieceCount?: number;
+  /** Full configuration object for customization */
+  config?: ConfettiConfig;
+  /** Callback when all pieces finish animating */
+  onComplete?: () => void;
+  
+  // === Legacy props for backward compatibility ===
+  /** @deprecated Use config.texts instead */
+  partner1Name?: string;
+  /** @deprecated Use config.texts instead */
+  partner2Name?: string;
+  /** @deprecated Use config.images instead */
+  partner1Avatar?: string;
+  /** @deprecated Use config.images instead */
+  partner2Avatar?: string;
+  /** @deprecated Use config instead */
+  variant?: 'love' | 'hearts-only';
+}
+
+// ============================================================================
+// DEFAULT VALUES
+// ============================================================================
+
+/** Default heart/love emojis */
+export const DEFAULT_EMOJIS = ['❤️', '💕', '💖', '💗', '💝', '💘', '💓', '💞', '🩷', '♥️'];
+
+/** Default love-themed colors */
+export const DEFAULT_COLORS = [
+  '#E29588', // Primary pink
+  '#FF6B8A', // Bright pink
+  '#FF85A2', // Light pink
+  '#FFB6C1', // Light pink 2
+  '#FFC0CB', // Pink
+  '#FF69B4', // Hot pink
+  '#FF1493', // Deep pink
+  '#DB7093', // Pale violet red
+  '#E67E92', // Rose
+  '#F8A5B8', // Sakura pink
+];
+
+/** Default animation configuration */
+const DEFAULT_ANIMATION: Required<AnimationConfig> = {
+  minDuration: 3000,
+  maxDuration: 5000,
+  maxDelay: 1500,
+  minSway: 30,
+  maxSway: 90,
+  swayCycleDuration: 800,
+  maxRotation: 360,
+  fadeOutStart: 0.7,
+};
+
+/** Default size configuration */
+const DEFAULT_SIZES: Required<SizeConfig> = {
+  minScale: 0.5,
+  maxScale: 1.5,
+  emojiFontSize: 28,
+  textFontSize: 14,
+  initialCircleSize: 36,
+  initialFontSize: 18,
+  avatarSize: 40,
+};
+
+/** Default content distribution */
+const DEFAULT_DISTRIBUTION: Required<ContentDistribution> = {
+  emojis: 0.5,
+  texts: 0.2,
+  initials: 0.2,
+  images: 0.1,
+};
+
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+
+/** Merge user config with defaults */
+const mergeConfig = (config?: ConfettiConfig): Required<Omit<ConfettiConfig, 'customContent' | 'texts' | 'initials' | 'images'>> & ConfettiConfig => {
+  return {
+    emojis: config?.emojis ?? DEFAULT_EMOJIS,
+    texts: config?.texts,
+    initials: config?.initials,
+    images: config?.images,
+    customContent: config?.customContent,
+    distribution: { ...DEFAULT_DISTRIBUTION, ...config?.distribution },
+    colors: config?.colors ?? DEFAULT_COLORS,
+    animation: { ...DEFAULT_ANIMATION, ...config?.animation },
+    sizes: { ...DEFAULT_SIZES, ...config?.sizes },
+    styles: config?.styles,
+  };
+};
+
+/** Generate confetti pieces based on configuration */
+const generateConfettiPieces = (
+  direction: ConfettiDirection,
+  count: number,
+  config: ReturnType<typeof mergeConfig>,
+  // Legacy props
+  legacyTexts?: string[],
+  legacyImages?: string[],
+): ConfettiPiece[] => {
+  const pieces: ConfettiPiece[] = [];
+  const { emojis, texts, initials, images, customContent, distribution, colors, animation, sizes } = config;
+  
+  // Merge legacy props with config
+  const allTexts = texts ?? legacyTexts ?? [];
+  const allImages = images ?? legacyImages ?? [];
+  const allInitials = initials ?? allTexts.map(t => t.charAt(0).toUpperCase());
+  
+  // Calculate start and end positions based on direction
+  const isBottomToTop = direction === 'bottom-to-top';
+  const getStartY = () => isBottomToTop 
+    ? SCREEN_HEIGHT + 100 + Math.random() * 200 
+    : -100 - Math.random() * 200;
+  const getEndY = () => isBottomToTop 
+    ? -150 
+    : SCREEN_HEIGHT + 150;
+
+  for (let i = 0; i < count; i++) {
+    let type: ConfettiPieceType;
+    let content = '';
+    let imageUri: string | undefined;
+    let isInitial = false;
+    let pieceColor = colors[Math.floor(Math.random() * colors.length)];
+
+    // If custom content is provided, use weighted random selection
+    if (customContent && customContent.length > 0) {
+      const totalWeight = customContent.reduce((sum, item) => sum + (item.weight ?? 1), 0);
+      let random = Math.random() * totalWeight;
+      
+      for (const item of customContent) {
+        random -= item.weight ?? 1;
+        if (random <= 0) {
+          type = item.type;
+          if (item.type === 'image') {
+            imageUri = item.value;
+          } else {
+            content = item.value;
+          }
+          if (item.color) {
+            pieceColor = item.color;
+          }
+          break;
+        }
+      }
+      type = type! ?? 'emoji';
+    } else {
+      // Use distribution-based selection
+      const rand = Math.random();
+      const dist = distribution!;
+      
+      if (rand < dist.emojis! && emojis.length > 0) {
+        type = 'emoji';
+        content = emojis[Math.floor(Math.random() * emojis.length)];
+      } else if (rand < dist.emojis! + dist.initials! && allInitials.length > 0) {
+        type = 'text';
+        content = allInitials[Math.floor(Math.random() * allInitials.length)];
+        isInitial = true;
+      } else if (rand < dist.emojis! + dist.initials! + dist.texts! && allTexts.length > 0) {
+        type = 'text';
+        content = allTexts[Math.floor(Math.random() * allTexts.length)];
+      } else if (allImages.length > 0) {
+        type = 'image';
+        imageUri = allImages[Math.floor(Math.random() * allImages.length)];
+      } else {
+        // Fallback to emoji
+        type = 'emoji';
+        content = emojis[Math.floor(Math.random() * emojis.length)];
+      }
+    }
+
+    const duration = animation!.minDuration! + Math.random() * (animation!.maxDuration! - animation!.minDuration!);
+    const swayAmount = animation!.minSway! + Math.random() * (animation!.maxSway! - animation!.minSway!);
+    const scale = sizes!.minScale! + Math.random() * (sizes!.maxScale! - sizes!.minScale!);
+
+    pieces.push({
+      id: i,
+      type,
+      content,
+      imageUri,
+      isInitial,
+      startX: Math.random() * SCREEN_WIDTH,
+      startY: getStartY(),
+      endY: getEndY(),
+      rotation: Math.random() * animation!.maxRotation! * 2 - animation!.maxRotation!,
+      scale,
+      delay: Math.random() * animation!.maxDelay!,
+      duration,
+      swayAmount,
+      swayCycleDuration: animation!.swayCycleDuration!,
+      color: pieceColor,
+      direction,
+    });
+  }
+
+  return pieces;
+};
+
+// ============================================================================
+// COMPONENTS
+// ============================================================================
+
+interface ConfettiPieceComponentProps {
+  piece: ConfettiPiece;
+  config: ReturnType<typeof mergeConfig>;
+  onFinish: () => void;
+}
+
+/** Individual animated confetti piece */
+const ConfettiPieceComponent: React.FC<ConfettiPieceComponentProps> = ({ piece, config, onFinish }) => {
+  const translateY = useSharedValue(piece.startY);
+  const translateX = useSharedValue(piece.startX);
+  const rotate = useSharedValue(0);
+  const opacity = useSharedValue(1);
+
+  const { animation, sizes, styles: customStyles } = config;
+
+  useEffect(() => {
+    // Animate movement
+    translateY.value = withDelay(
+      piece.delay,
+      withTiming(piece.endY, {
+        duration: piece.duration,
+        easing: Easing.out(Easing.quad),
+      })
+    );
+
+    // Handle completion
+    const completionTimeout = setTimeout(() => {
+      onFinish();
+    }, piece.delay + piece.duration);
+
+    // Animate rotation
+    rotate.value = withDelay(
+      piece.delay,
+      withTiming(piece.rotation, {
+        duration: piece.duration,
+        easing: Easing.linear,
+      })
+    );
+
+    // Animate horizontal sway
+    const swayCycle = () => {
+      translateX.value = withTiming(
+        piece.startX + piece.swayAmount,
+        { duration: piece.swayCycleDuration, easing: Easing.inOut(Easing.sin) },
+        () => {
+          translateX.value = withTiming(
+            piece.startX - piece.swayAmount,
+            { duration: piece.swayCycleDuration, easing: Easing.inOut(Easing.sin) },
+            () => {
+              translateX.value = withTiming(
+                piece.startX,
+                { duration: piece.swayCycleDuration, easing: Easing.inOut(Easing.sin) }
+              );
+            }
+          );
+        }
+      );
+    };
+
+    const timeout = setTimeout(swayCycle, piece.delay);
+
+    // Fade out
+    opacity.value = withDelay(
+      piece.delay + piece.duration * animation!.fadeOutStart!,
+      withTiming(0, { duration: piece.duration * (1 - animation!.fadeOutStart!) })
+    );
+
+    return () => {
+      clearTimeout(timeout);
+      clearTimeout(completionTimeout);
+    };
+  }, []);
+
+  const animatedStyle = useAnimatedStyle(() => {
+    return {
+      transform: [
+        { translateX: translateX.value },
+        { translateY: translateY.value },
+        { rotate: `${rotate.value}deg` },
+        { scale: piece.scale },
+      ],
+      opacity: opacity.value,
+    };
+  });
+
+  const renderContent = () => {
+    switch (piece.type) {
+      case 'emoji':
+        return (
+          <Text style={[
+            styles.emoji,
+            { fontSize: sizes!.emojiFontSize },
+            customStyles?.emoji
+          ]}>
+            {piece.content}
+          </Text>
+        );
+      case 'text':
+        if (piece.isInitial) {
+          return (
+            <View style={[
+              styles.initialCircle,
+              { 
+                width: sizes!.initialCircleSize,
+                height: sizes!.initialCircleSize,
+                borderRadius: sizes!.initialCircleSize! / 2,
+                backgroundColor: `${piece.color}30` 
+              },
+              customStyles?.initialCircle
+            ]}>
+              <Text style={[
+                styles.initialText,
+                { fontSize: sizes!.initialFontSize, color: piece.color },
+                customStyles?.initialText
+              ]}>
+                {piece.content}
+              </Text>
+            </View>
+          );
+        }
+        return (
+          <Text style={[
+            styles.text,
+            { fontSize: sizes!.textFontSize, color: piece.color },
+            customStyles?.text
+          ]}>
+            {piece.content}
+          </Text>
+        );
+      case 'image':
+        return (
+          <View style={[
+            styles.imageContainer,
+            { 
+              width: sizes!.avatarSize,
+              height: sizes!.avatarSize,
+              borderRadius: sizes!.avatarSize! / 2
+            },
+            customStyles?.imageContainer
+          ]}>
+            <Image
+              source={{ uri: piece.imageUri }}
+              style={[styles.image, customStyles?.image]}
+              contentFit="cover"
+            />
+          </View>
+        );
+      default:
+        return null;
+    }
+  };
+
+  return (
+    <Animated.View style={[styles.confettiPiece, animatedStyle]}>
+      {renderContent()}
+    </Animated.View>
+  );
+};
+
+/** Main Confetti Component */
+const Confetti: React.FC<ConfettiProps> = ({
+  isVisible,
+  direction = 'top-to-bottom',
+  pieceCount = 55,
+  config,
+  onComplete,
+  // Legacy props
+  partner1Name,
+  partner2Name,
+  partner1Avatar,
+  partner2Avatar,
+  variant,
+}) => {
+  const [pieces, setPieces] = useState<ConfettiPiece[]>([]);
+  const finishedCount = useRef(0);
+  const totalPieces = useRef(0);
+
+  // Merge configuration with defaults
+  const mergedConfig = React.useMemo(() => {
+    // Handle legacy variant prop
+    if (variant === 'hearts-only') {
+      return mergeConfig({
+        ...config,
+        distribution: { emojis: 1, texts: 0, initials: 0, images: 0 },
+      });
+    }
+    return mergeConfig(config);
+  }, [config, variant]);
+
+  // Build legacy arrays for backward compatibility
+  const legacyTexts = React.useMemo(() => {
+    const texts: string[] = [];
+    if (partner1Name) texts.push(partner1Name);
+    if (partner2Name) texts.push(partner2Name);
+    return texts.length > 0 ? texts : undefined;
+  }, [partner1Name, partner2Name]);
+
+  const legacyImages = React.useMemo(() => {
+    const images: string[] = [];
+    if (partner1Avatar) images.push(partner1Avatar);
+    if (partner2Avatar) images.push(partner2Avatar);
+    return images.length > 0 ? images : undefined;
+  }, [partner1Avatar, partner2Avatar]);
+
+  useEffect(() => {
+    if (isVisible) {
+      const newPieces = generateConfettiPieces(
+        direction,
+        pieceCount,
+        mergedConfig,
+        legacyTexts,
+        legacyImages
+      );
+      setPieces(newPieces);
+      totalPieces.current = newPieces.length;
+      finishedCount.current = 0;
+    } else {
+      setPieces([]);
+    }
+  }, [isVisible, direction, pieceCount, mergedConfig, legacyTexts, legacyImages]);
+
+  const handlePieceFinish = useCallback(() => {
+    finishedCount.current += 1;
+    if (finishedCount.current >= totalPieces.current && onComplete) {
+      onComplete();
+    }
+  }, [onComplete]);
+
+  if (!isVisible || pieces.length === 0) {
+    return null;
+  }
+
+  return (
+    <View style={styles.container} pointerEvents="none">
+      {pieces.map((piece) => (
+        <ConfettiPieceComponent
+          key={piece.id}
+          piece={piece}
+          config={mergedConfig}
+          onFinish={handlePieceFinish}
+        />
+      ))}
+    </View>
+  );
+};
+
+// ============================================================================
+// STYLES
+// ============================================================================
+
+const styles = StyleSheet.create({
+  container: {
+    ...StyleSheet.absoluteFillObject,
+    zIndex: 9999,
+    elevation: 9999,
+  },
+  confettiPiece: {
+    position: 'absolute',
+  },
+  emoji: {
+    fontSize: 28,
+    textShadowColor: 'rgba(0, 0, 0, 0.1)',
+    textShadowOffset: { width: 1, height: 1 },
+    textShadowRadius: 2,
+  },
+  text: {
+    fontSize: 14,
+    fontWeight: '600',
+    textShadowColor: 'rgba(0, 0, 0, 0.15)',
+    textShadowOffset: { width: 1, height: 1 },
+    textShadowRadius: 2,
+  },
+  initialCircle: {
+    width: 36,
+    height: 36,
+    borderRadius: 18,
+    alignItems: 'center',
+    justifyContent: 'center',
+    borderWidth: 2,
+    borderColor: 'rgba(255, 255, 255, 0.5)',
+  },
+  initialText: {
+    fontSize: 18,
+    fontWeight: '700',
+  },
+  imageContainer: {
+    width: 40,
+    height: 40,
+    borderRadius: 20,
+    overflow: 'hidden',
+    borderWidth: 2,
+    borderColor: 'rgba(255, 255, 255, 0.6)',
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.2,
+    shadowRadius: 4,
+    elevation: 4,
+  },
+  image: {
+    width: '100%',
+    height: '100%',
+  },
+});
+
+export default Confetti;

package/src/LoveConfetti.tsx

@@ -0,0 +1,34 @@
+/**
+ * LoveConfetti - A wrapper around the base Confetti component
+ * for backward compatibility with existing usage.
+ * 
+ * For new implementations, consider using the Confetti component directly
+ * with the appropriate variant and direction props.
+ */
+
+import React from 'react';
+import Confetti, { ConfettiConfig } from './Confetti';
+
+interface LoveConfettiProps {
+  isVisible: boolean;
+  config?: ConfettiConfig;
+  onComplete: () => void;
+}
+
+const LoveConfetti: React.FC<LoveConfettiProps> = ({
+  isVisible,
+  config,
+  onComplete,
+}) => {
+  return (
+    <Confetti
+      isVisible={isVisible}
+      direction="top-to-bottom"
+      pieceCount={55}
+      config={config}
+      onComplete={onComplete}
+    />
+  );
+};
+
+export default LoveConfetti;

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * rn-confetti-love
+ * Beautiful animated confetti effects for React Native
+ */
+
+// Main components
+export { default as Confetti } from './Confetti';
+export { default as LoveConfetti } from './LoveConfetti';
+
+// Types
+export type {
+  ConfettiProps,
+  ConfettiDirection,
+  ConfettiConfig,
+  ConfettiPieceType,
+  AnimationConfig,
+  SizeConfig,
+  ConfettiContentItem,
+  ContentDistribution,
+  ConfettiStyles,
+} from './Confetti';