animated-backgrounds/README.md

A feature-rich React package for stunning animated backgrounds with interactive controls, themes, performance monitoring, and layered compositions.

# Animated Backgrounds [![Socket Badge](https://socket.dev/api/badge/npm/package/animated-backgrounds/1.1.0)](https://socket.dev/npm/package/animated-backgrounds/overview/1.1.0)

[![npm](https://img.shields.io/npm/dm/animated-backgrounds.svg)](https://www.npmjs.com/package/animated-backgrounds)
![License](https://img.shields.io/github/license/umerfarok/animated-backgrounds)
![npm](https://img.shields.io/npm/v/animated-backgrounds)
![GitHub stars](https://img.shields.io/github/stars/umerfarok/animated-backgrounds)

🎨 **A feature-rich React package for stunning animated backgrounds with advanced controls, themes, and interactivity.**

## 🌟 **New Features in v2.0**
- 🎮 **Interactive animations** with mouse/touch support
- 🎨 **Theme system** with predefined color schemes  
- 📊 **Performance monitoring** and adaptive optimization
- 🎛️ **Animation controls** (play/pause/speed/reset)
- 🏗️ **Layered backgrounds** for complex compositions
- 📱 **Mobile-optimized** with gesture recognition
- 🎯 **Preset configurations** for quick setup

Sample implementation https://qr-generator-murex.vercel.app/
## Docs https://umerfarok.github.io/animated-backgrounds/

## Installation

```bash
npm install animated-backgrounds
```

or

```bash
yarn add animated-backgrounds
```

## 🚀 **Quick Start**

### Basic Usage

```jsx
import React from 'react';
import { AnimatedBackground } from 'animated-backgrounds';

function App() {
  return (
    <div>
      <AnimatedBackground 
        animationName="starryNight" 
        blendMode="screen" 
      />
      {/* Your app content */}
    </div>
  );
}

export default App;
```

### 🎨 **Theme-Based Usage**

```jsx
import React from 'react';
import { AnimatedBackground } from 'animated-backgrounds';

function App() {
  return (
    <div>
      {/* Gaming theme with cyberpunk colors */}
      <AnimatedBackground 
        animationName="matrixRain"
        theme="gaming"
        interactive={true}
        enablePerformanceMonitoring={true}
      />
      
      {/* Wellness theme with nature colors */}
      <AnimatedBackground 
        animationName="oceanWaves"
        theme="wellness"
        adaptivePerformance={true}
      />
    </div>
  );
}
```

### 🎮 **Interactive Animations**

```jsx
import React from 'react';
import { AnimatedBackground } from 'animated-backgrounds';

function App() {
  return (
    <div>
      <AnimatedBackground 
        animationName="particleNetwork"
        interactive={true}
        interactionConfig={{
          effect: 'attract',     // 'attract', 'repel', 'follow', 'burst'
          strength: 0.8,         // 0-1
          radius: 150,           // pixels
          continuous: true       // keep effect after mouse leaves
        }}
      />
    </div>
  );
}
```

### 🏗️ **Layered Backgrounds**

```jsx
import React from 'react';
import { LayeredBackground } from 'animated-backgrounds';

function App() {
  const layers = [
    { 
      animation: 'starryNight', 
      opacity: 0.7, 
      blendMode: 'normal',
      speed: 0.5 
    },
    { 
      animation: 'particleNetwork', 
      opacity: 0.3, 
      blendMode: 'screen',
      speed: 1.2 
    },
    { 
      animation: 'cosmicDust', 
      opacity: 0.5, 
      blendMode: 'overlay',
      speed: 0.8 
    }
  ];

  return (
    <div>
      <LayeredBackground layers={layers} />
      {/* Your content */}
    </div>
  );
}
```

### 🎛️ **Animation Controls**

```jsx
import React from 'react';
import { AnimatedBackground, useAnimationControls } from 'animated-backgrounds';

function App() {
  const controls = useAnimationControls({
    initialSpeed: 1,
    autoPlay: true
  });

  return (
    <div>
      <AnimatedBackground 
        animationName="galaxySpiral"
        animationControls={controls}
      />
      
      <div className="controls">
        <button onClick={controls.play}>Play</button>
        <button onClick={controls.pause}>Pause</button>
        <button onClick={controls.reset}>Reset</button>
        <button onClick={() => controls.setSpeed(0.5)}>Slow</button>
        <button onClick={() => controls.setSpeed(2.0)}>Fast</button>
      </div>
    </div>
  );
}
```

### 📊 **Performance Monitoring**

```jsx
import React from 'react';
import { AnimatedBackground, usePerformanceMonitor } from 'animated-backgrounds';

function App() {
  const performance = usePerformanceMonitor({
    warningThreshold: 30,
    autoOptimize: true
  });

  return (
    <div>
      <AnimatedBackground 
        animationName="electricStorm"
        enablePerformanceMonitoring={true}
        adaptivePerformance={true}
      />
      
      {/* Performance Display */}
      <div className="performance-info">
        <p>FPS: {performance?.fps}</p>
        <p>Performance: {performance?.performanceLevel}</p>
        {performance?.warnings.map((warning, i) => (
          <p key={i} className="warning">{warning}</p>
        ))}
      </div>
    </div>
  );
}
```

## 🎨 **Available Themes**

```jsx
// Available preset themes
const themes = [
  'gaming',      // Cyberpunk colors, high intensity
  'portfolio',   // Monochrome, professional
  'landing',     // Sunset colors, medium intensity
  'presentation', // Space colors, low intensity
  'wellness',    // Nature colors, calming
  'party'        // Neon colors, high energy
];

<AnimatedBackground animationName="neonPulse" theme="gaming" />
```

## 🎯 **Preset Configurations**

```jsx
// Quick setup with presets
<AnimatedBackground preset="gaming" />
<AnimatedBackground preset="portfolio" />
<AnimatedBackground preset="landing" />
```

## 📱 **Mobile & Touch Support**

```jsx
import React from 'react';
import { AnimatedBackground } from 'animated-backgrounds';

function App() {
  return (
    <div>
      <AnimatedBackground 
        animationName="fireflyForest"
        interactive={true}
        interactionConfig={{
          effect: 'follow',
          strength: 0.6,
          radius: 100
        }}
        // Automatically optimizes for mobile
        adaptivePerformance={true}
      />
    </div>
  );
}
```

## 🛠️ **Custom Theme Creation**

```jsx
import { themeManager, COLOR_SCHEMES } from 'animated-backgrounds';

// Create custom theme
themeManager.createCustomTheme('myTheme', {
  name: 'My Custom Theme',
  colorScheme: {
    name: 'Custom',
    colors: ['#ff6b6b', '#4ecdc4', '#45b7d1', '#96ceb4', '#feca57'],
    gradients: {
      primary: ['#ff6b6b', '#4ecdc4'],
      secondary: ['#45b7d1', '#96ceb4'],
      accent: ['#96ceb4', '#feca57']
    },
    effects: {
      glow: '#4ecdc4',
      highlight: '#feca57',
      shadow: '#2c3e50'
    }
  },
  animationSettings: {
    intensity: 'medium',
    speed: 1.0,
    particleCount: 100,
    glowEffect: true
  },
  recommendedAnimations: ['particleNetwork', 'cosmicDust']
});

// Use custom theme
<AnimatedBackground animationName="particleNetwork" theme="myTheme" />
```

## 🎤 **Animated Text Components**

```jsx
import React from 'react';
import { AnimatedText } from 'animated-backgrounds';

function App() {
  return (
    <div>
      {/* Basic text animations */}
      <AnimatedText 
        text="Hello World!"
        effect="typewriter"
        config={{
          speed: 100,
          loop: true,
          delay: 1000
        }}
      />

      <AnimatedText 
        text="Rainbow Text"
        effect="rainbow"
      />

      <AnimatedText 
        text="Glitch Effect"
        effect="glitch"
      />

      {/* Bounce effect */}
      <AnimatedText 
        text="Bouncing Letters"
        effect="bounce"
        styles={{
          fontSize: '2em',
          fontWeight: 'bold'
        }}
      />
    </div>
  );
}
```

## 🎪 **Advanced Examples**

### Multi-layered Gaming Background
```jsx
const gamingLayers = [
  { animation: 'matrixRain', opacity: 0.8, blendMode: 'normal' },
  { animation: 'electricStorm', opacity: 0.4, blendMode: 'screen' },
  { animation: 'neonPulse', opacity: 0.3, blendMode: 'overlay' }
];

<LayeredBackground 
  layers={gamingLayers}
  enablePerformanceMonitoring={true}
/>
```

### Interactive Portfolio Background
```jsx
<AnimatedBackground 
  animationName="geometricShapes"
  theme="portfolio"
  interactive={true}
  interactionConfig={{
    effect: 'attract',
    strength: 0.3,
    radius: 200,
    continuous: false
  }}
  adaptivePerformance={true}
/>
```

## Usage in Next.js with SSR
When using in Next.js projects with server-side rendering (SSR), add the "use client" directive:

```jsx
"use client";

import React from 'react';
import { AnimatedBackground } from 'animated-backgrounds';

const Home = () => {
  return (
    <div>
      <h1>Welcome to Next.js with Animated Backgrounds</h1>
      <AnimatedBackground 
        animationName="starryNight" 
        theme="presentation"
        adaptivePerformance={true}
      />
    </div>
  );
};  

export default Home;
```

## 🎨 **Available Animations**

The package includes 20+ stunning animations:

**Space & Cosmic:**
- `starryNight` - Twinkling stars
- `galaxySpiral` - Rotating galaxy
- `cosmicDust` - Floating space particles
- `quantumField` - Quantum physics inspired

**Nature & Elements:**
- `oceanWaves` - Flowing water simulation
- `autumnLeaves` - Falling leaves
- `fireflies` - Glowing insects
- `snowFall` - Winter snow effect

**Technology & Cyber:**
- `matrixRain` - Matrix-style code rain
- `electricStorm` - Lightning effects
- `neonPulse` - Pulsing neon lights
- `particleNetwork` - Connected particles

**Abstract & Artistic:**
- `geometricShapes` - Moving geometric forms
- `rainbowWaves` - Colorful wave patterns
- `gradientWave` - Smooth gradient transitions
- `floatingBubbles` - Bubble simulation

**Special Effects:**
- `auroraBorealis` - Northern lights
- `neuralNetwork` - Brain-like connections
- `dnaHelix` - DNA strand animation
- `fallingFoodFiesta` - Fun food particles

## 🎯 **Blend Modes**

Enhance your backgrounds with CSS blend modes:

```jsx
<AnimatedBackground 
  animationName="starryNight" 
  blendMode="screen"     // Creates light, glowing effects
/>

<AnimatedBackground 
  animationName="particleNetwork" 
  blendMode="multiply"   // Creates darker, atmospheric effects
/>
```

Available blend modes: `normal`, `multiply`, `screen`, `overlay`, `darken`, `lighten`, `color-dodge`, `color-burn`, `hard-light`, `soft-light`, `difference`, `exclusion`, `hue`, `saturation`, `color`, `luminosity`

## 🚀 **Performance Tips**

1. **Use adaptive performance** for automatic optimization
2. **Enable performance monitoring** to track FPS
3. **Choose appropriate themes** for your use case
4. **Use lower particle counts** on mobile devices
5. **Consider layered backgrounds** for complex effects

```jsx
// Optimized for performance
<AnimatedBackground 
  animationName="starryNight"
  adaptivePerformance={true}
  enablePerformanceMonitoring={true}
  fps={30} // Lower FPS for better performance
/>
```

## 📚 **API Reference**

### AnimatedBackground Props
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `animationName` | string | required | Name of the animation |
| `theme` | string | undefined | Theme to apply |
| `interactive` | boolean | false | Enable interactions |
| `fps` | number | 60 | Frames per second |
| `blendMode` | string | 'normal' | CSS blend mode |
| `adaptivePerformance` | boolean | false | Auto-optimize performance |

### Theme System
```jsx
import { themeManager, THEMES, COLOR_SCHEMES } from 'animated-backgrounds';

// Available themes
console.log(Object.keys(THEMES));

// Available color schemes  
console.log(Object.keys(COLOR_SCHEMES));

// Apply theme
themeManager.applyTheme('gaming');
```

### Performance Monitoring
```jsx
import { usePerformanceMonitor } from 'animated-backgrounds';

const perf = usePerformanceMonitor({
  sampleSize: 60,
  warningThreshold: 30
});

// Access performance data
console.log(perf.fps, perf.avgFps, perf.performanceLevel);
```

## 🤝 **Contributing**

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## 📄 **License**

MIT License - see the [LICENSE](LICENSE) file for details.

## 🌟 **Show Your Support**

If you like this project, please give it a ⭐ on [GitHub](https://github.com/umerfarok/animated-backgrounds)!

---

**Made with ❤️ by [Umer Farooq](https://github.com/umerfarok)**