@mmdalipour/particle-morph

A highly configurable React component for creating stunning 3D particle morph effects with Three.js and React Three Fiber.

Features

• 🎭 Multi-Stage Morphing - Seamlessly morph between multiple geometric shapes
• 💥 Explosion Effects - Realistic particle explosions with physics-based motion
• 🎨 Custom 3D Models - Convert any GLTF model into interactive particles
• 🌈 Color Transitions - Smooth color transitions between stages
• 🖱️ Interactive Rotation - Drag to rotate with inertia and smooth damping
• 📜 Scroll Integration - Animate based on scroll progress with smooth interpolation
• 💫 Glow Effects - Beautiful particle glow with customizable intensity
• ⚡ Optimized Performance - Highly optimized shaders and rendering pipeline
• 🎯 TypeScript - Full TypeScript support with comprehensive types
• 📦 Tree-shakeable - Modular exports for optimal bundle size

Installation

npm install @mmdalipour/particle-morph
# or
yarn add @mmdalipour/particle-morph
# or
pnpm add @mmdalipour/particle-morph

Peer Dependencies

npm install react react-dom three @react-three/fiber @react-three/drei @react-three/postprocessing gsap postprocessing

Quick Start

import { ParticleMorph } from '@mmdalipour/particle-morph';

function App() {
  return (
    <ParticleMorph
      stages={[
        {
          shape: { type: 'sphere', size: 5 },
          scrollStart: 0,
          scrollEnd: 0.5,
          color: '#00ffff',
        },
        {
          shape: { type: 'box', size: 5 },
          scrollStart: 0.5,
          scrollEnd: 1,
          color: '#ff00ff',
        },
      ]}
      targetParticleCount={5000}
      particleColor="#00ffff"
    />
  );
}

API Reference

ParticleMorph Component

Props

interface ParticleMorphConfig {
  // Required
  stages: ShapeStage[];                // Array of shape stages to morph through

  // Optional
  targetParticleCount?: number;        // Number of particles (default: 5000)
  particleColor?: string;              // Default color for all stages (default: '#ffffff')
  particleSize?: number;               // Base particle size (default: 3)
  particleSizeRange?: {
    min?: number;                      // Min size multiplier (default: 0.2)
    max?: number;                      // Max size multiplier (default: 2.0)
  };
  camera?: {
    position?: [number, number, number]; // Camera position (default: [0, 0, 10])
    fov?: number;                      // Field of view (default: 75)
  };
  rotation?: {
    x?: number;                        // Initial rotation X in radians (default: 0)
    y?: number;                        // Initial rotation Y in radians (default: 0)
    z?: number;                        // Initial rotation Z in radians (default: 0)
    autoRotate?: {
      enabled?: boolean;               // Enable auto-rotation (default: true)
      dampingFactor?: number;          // Auto-rotation smoothness (default: 0.05)
      speed?: {
        x?: number;                    // Auto-rotate X speed (default: 0)
        y?: number;                    // Auto-rotate Y speed (default: 0)
        z?: number;                    // Auto-rotate Z speed (default: 0)
      };
    };
  };
  particleAnimation?: {
    enabled?: boolean;                 // Enable drift animation (default: true)
    dampingFactor?: number;            // Animation strength (default: 0.5)
    driftSpeed?: number;               // Drift speed (default: 0.5)
    driftAmplitude?: number;           // Drift amount (default: 0.15)
  };
  className?: string;                  // CSS class
  style?: React.CSSProperties;         // Inline styles
}

interface ShapeStage {
  shape: ShapeConfig;                  // Shape configuration
  scrollStart: number;                 // Start scroll position (0-1)
  scrollEnd: number;                   // End scroll position (0-1)
  color?: string;                      // Stage color (overrides particleColor)
  explosion?: {
    enabled: boolean;                  // Enable explosion effect
    radius: number;                    // Explosion radius
  };
}

interface ShapeConfig {
  type: 'sphere' | 'box' | 'torus' | 'cone' | 'cylinder' | 
        'dodecahedron' | 'octahedron' | 'tetrahedron' | 'model';
  size?: number;                       // Shape size (default: 5)
  modelPath?: string;                  // Required when type is 'model'
}

Examples

Basic Morph

<ParticleMorph
  stages={[
    {
      shape: { type: 'sphere', size: 5 },
      scrollStart: 0,
      scrollEnd: 0.5,
      color: '#00ffff',
    },
    {
      shape: { type: 'box', size: 5 },
      scrollStart: 0.5,
      scrollEnd: 1,
      color: '#ff00ff',
    },
  ]}
  targetParticleCount={5000}
/>

Explosion Effect

<ParticleMorph
  stages={[
    {
      shape: { type: 'box', size: 5 },
      scrollStart: 0,
      scrollEnd: 0.5,
      color: '#00ffff',
    },
    {
      shape: { type: 'sphere', size: 5 },
      scrollStart: 0.5,
      scrollEnd: 1,
      color: '#ff00ff',
      explosion: {
        enabled: true,
        radius: 50,
      },
    },
  ]}
  targetParticleCount={10000}
/>

Multi-Stage Morphing

<ParticleMorph
  stages={[
    { shape: { type: 'sphere', size: 5 }, scrollStart: 0, scrollEnd: 0.25, color: '#00ffff' },
    { shape: { type: 'torus', size: 3 }, scrollStart: 0.25, scrollEnd: 0.5, color: '#0088ff' },
    { shape: { type: 'dodecahedron', size: 5 }, scrollStart: 0.5, scrollEnd: 0.75, color: '#ff00ff' },
    { shape: { type: 'octahedron', size: 5 }, scrollStart: 0.75, scrollEnd: 1, color: '#ffff00' },
  ]}
  targetParticleCount={8000}
  particleAnimation={{
    enabled: true,
    dampingFactor: 0.8,
    driftSpeed: 1.0,
    driftAmplitude: 0.3,
  }}
/>

Custom 3D Model

<ParticleMorph
  stages={[
    {
      shape: { type: 'model', modelPath: '/models/your-model.glb' },
      scrollStart: 0,
      scrollEnd: 0.5,
      color: '#00ffff',
    },
    {
      shape: { type: 'sphere', size: 5 },
      scrollStart: 0.5,
      scrollEnd: 1,
      color: '#ff00ff',
      explosion: { enabled: true, radius: 40 },
    },
  ]}
  targetParticleCount={8000}
/>

High Performance Settings

<ParticleMorph
  stages={[...]}
  targetParticleCount={5000}
  glow={{
    enabled: true,
    intensity: 1.2,
    coverage: 0.2,
  }}
  particleAnimation={{
    enabled: true,
    dampingFactor: 0.4,
  }}
/>

Available Shapes

• sphere - Perfect sphere with uniform particle distribution
• box - Cubic shape
• torus - Donut shape
• cone - Cone shape
• cylinder - Cylindrical shape
• dodecahedron - 12-faced polyhedron
• octahedron - 8-faced polyhedron
• tetrahedron - 4-faced polyhedron
• model - Custom GLTF/GLB 3D model

Performance Tips

1. Particle Count: Start with 5000-8000 particles. Adjust based on device performance
2. Glow: Reduce glow intensity or disable on lower-end devices
3. Particle Animation: Disable or reduce drift for better performance
4. Stage Count: Limit to 4 stages maximum for optimal performance

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 15+
• Requires WebGL 2.0 support

Version History

1.3.0

• ✨ Added particleColor prop for default particle color
• 🎨 Removed segments parameter (now uses optimal defaults)
• 💥 Improved explosion physics with realistic motion
• ⚡ Major performance optimizations (shader improvements, throttled scroll, reduced DPR)
• 🌐 Fixed sphere particle distribution with Fibonacci algorithm
• 🔧 Better scroll handling with requestAnimationFrame

1.2.0

• Multi-stage morphing support
• Explosion effects
• Color transitions

1.1.0

• Interactive rotation
• Glow effects
• Performance improvements

1.0.0

• Initial release

License

MIT © Mohammad Alipour

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Links

• GitHub Repository
• Report Issues
• npm Package