Vanta React

한국어 문서 | English

A React component library for Vanta.js animated backgrounds with automatic library loading and ultra-lightweight bundles.

🌟 Key Features

• 📦 Ultra-Light Bundle: ~21KB CDN-optimized package
• 🚀 Zero Setup: Just install and use - automatic library loading
• 🌐 CDN Optimized: Three.js, p5.js, and Vanta loaded from CDN
• ⚡ Smart Caching: Libraries cached across your entire website
• 🛡️ Error Recovery: Built-in retry mechanisms and fallback handling
• 🎨 14 Vanta Effects: Support for all Vanta.js effects
• 🔧 TypeScript: Complete type safety and IntelliSense support
• ⚛️ React 16+: Compatible with all modern React versions
• 🔇 Silent Operation: Clean console output without debug messages

Installation

# npm
npm install vanta-react

# yarn  
yarn add vanta-react

# pnpm
pnpm add vanta-react

Quick Start

1. Basic Usage (Automatic Loading)

import React from 'react';
import { Vanta } from 'vanta-react';

function App() {
  return (
    <Vanta
      effect="waves"
      options={{
        mouseControls: true,
        touchControls: true,
        color: 0x3f6b7d
      }}
    />
  );
}

2. Full Screen Background

import React from 'react';
import { Vanta } from 'vanta-react';

function FullScreenExample() {
  return (
    <div>
      <Vanta
        effect="net"
        background={true}
        options={{
          color: 0x3f7fb3,
          points: 8.00,
          maxDistance: 23.00,
          spacing: 17.00,
        }}
      />
      
      <div style={{ position: 'relative', zIndex: 1 }}>
        <h1>Your Content Here</h1>
      </div>
    </div>
  );
}

3. Custom Loading UI

import React from 'react';
import { Vanta } from 'vanta-react';

const CustomLoader = () => (
  <div style={{ 
    display: 'flex', 
    alignItems: 'center', 
    justifyContent: 'center',
    height: '200px',
    backgroundColor: '#f0f8ff',
    border: '2px dashed #4a90e2'
  }}>
    <div>🚀 Loading Vanta Effect...</div>
  </div>
);

function CustomLoadingExample() {
  return (
    <Vanta
      effect="waves"
      loadingComponent={<CustomLoader />}
      onLoadStart={() => console.log('🔄 Loading started')}
      onLoadSuccess={() => console.log('✅ Loading completed')}
      onLoadError={(error) => console.error('❌ Loading failed:', error)}
      options={{ color: 0x667eea }}
    />
  );
}

Usage

Basic Usage

import React from 'react';
import { Vanta } from 'vanta-react';

function App() {
  return (
    <div>
      {/* Libraries are automatically loaded - no setup required! */}
      <Vanta
        effect="waves"
        options={{
          color: 0x3f6b7d,
          waveHeight: 20,
        }}
      />
    </div>
  );
}

Custom Loading UI

import React from 'react';
import { Vanta } from 'vanta-react';

const CustomLoader = () => (
  <div style={{ textAlign: 'center', padding: '50px' }}>
    <div>🌐 Loading Vanta Effects...</div>
  </div>
);

function AppWithCustomLoader() {
  return (
    <Vanta
      effect="net"
      loadingComponent={<CustomLoader />}
      onLoadStart={() => console.log('Loading started')}
      onLoadSuccess={() => console.log('Loading completed')}
      onLoadError={(error) => console.error('Loading failed:', error)}
      options={{ color: 0x3f7fb3 }}
    />
  );
}

Configuration

Default Behavior

By default, Vanta components automatically load required libraries:

// Just works - no setup needed!
<Vanta effect="net" options={{ color: 0x3f7fb3 }} />

Props Reference

| Prop | Type | Default | Description | |------|------|---------|-------------| | autoLoad | boolean | true | Enable/disable automatic library loading | | loadingComponent | ReactNode | Built-in spinner | Custom loading UI component | | errorComponent | ReactNode \| Function | Built-in error UI | Custom error UI component or render function | | retryCount | number | 3 | Number of retry attempts on loading failure | | retryDelay | number | 1000 | Delay between retries (milliseconds) | | onLoadStart | () => void | - | Callback when loading starts | | onLoadSuccess | () => void | - | Callback when loading succeeds | | onLoadError | (error: string) => void | - | Callback when loading fails |

Custom Error Handling

const CustomErrorComponent = ({ error, retry }) => (
  <div style={{ padding: '20px', textAlign: 'center', border: '2px dashed #ff6b6b' }}>
    <div>❌ Failed to load Vanta effect</div>
    <div style={{ fontSize: '12px', color: '#666', margin: '8px 0' }}>{error}</div>
    <button onClick={retry} style={{ padding: '8px 16px' }}>
      🔄 Retry
    </button>
  </div>
);

function ErrorHandlingExample() {
  return (
    <Vanta
      effect="waves"
      errorComponent={CustomErrorComponent}
      retryCount={5}
      retryDelay={2000}
      options={{ color: 0x667eea }}
    />
  );
}

Disabling Auto-Loading (Manual Control)

For manual control or specific use cases, you can disable auto-loading:

import React, { useEffect, useState } from 'react';
import { Vanta, preloadLibraries } from 'vanta-react';

function ManualLoadingExample() {
  const [isReady, setIsReady] = useState(false);

  useEffect(() => {
    const loadLibraries = async () => {
      try {
        await preloadLibraries();
        setIsReady(true);
      } catch (error) {
        console.error('Failed to load libraries:', error);
      }
    };

    loadLibraries();
  }, []);

  if (!isReady) {
    return <div>Loading libraries...</div>;
  }

  return (
    <Vanta
      effect="net"
      autoLoad={false}  // Disable auto-loading
      options={{ color: 0x3f7fb3 }}
    />
  );
}

CDN Library Management

Preload Status Monitoring

import { getPreloadStatus, areLibrariesReady } from 'vanta-react';

function StatusMonitor() {
  const status = getPreloadStatus();
  
  return (
    <div>
      <div>Libraries Ready: {areLibrariesReady() ? '✅' : '❌'}</div>
      <div>Load Source: {status.loadSource}</div>
      <div>THREE.js: {status.threeAvailable ? '✅' : '❌'}</div>
      <div>p5.js: {status.p5Available ? '✅' : '❌'}</div>
      {status.hasError && <div>Error: {status.error}</div>}
    </div>
  );
}

Dynamic Effect Loading

import { loadVantaEffectFromCdn, getVantaLoadStatus } from 'vanta-react';

async function loadEffect(effectName) {
  try {
    await loadVantaEffectFromCdn(effectName);
    const status = getVantaLoadStatus();
    console.log(`Loaded effects: ${status.loadedEffects.join(', ')}`);
  } catch (error) {
    console.error(`Failed to load ${effectName}:`, error);
  }
}

Props Reference

| Prop | Type | Required | Description | |------|------|----------|-------------| | effect | VantaEffectName | ✅ | The name of the Vanta effect to render | | background | boolean | ❌ | true: Full screen background, false: Container mode (default: false) | | options | Record<string, any> | ❌ | Configuration options to pass to the Vanta effect | | className | string | ❌ | Additional CSS class name to apply | | style | React.CSSProperties | ❌ | Inline styles to apply to the container | | autoLoad | boolean | ❌ | Enable/disable automatic library loading (default: true) | | loadingComponent | ReactNode | ❌ | Custom loading UI component | | errorComponent | ReactNode \| Function | ❌ | Custom error UI component or render function | | retryCount | number | ❌ | Number of retry attempts on loading failure (default: 3) | | retryDelay | number | ❌ | Delay between retries in milliseconds (default: 1000) | | onLoadStart | () => void | ❌ | Callback when loading starts | | onLoadSuccess | () => void | ❌ | Callback when loading succeeds | | onLoadError | (error: string) => void | ❌ | Callback when loading fails |

Supported Effects

• birds - Animated bird flock
• cells - Cell structure animation
• clouds - Cloud animation
• clouds2 - Cloud animation (variant)
• dots - Dot animation (requires p5.js)
• fog - Fog effect
• globe - Globe effect
• halo - Halo effect
• net - Network connection animation
• rings - Circular animation
• ripple - Ripple effect
• topology - Topology animation (requires p5.js)
• trunk - Tree trunk animation (requires p5.js)
• waves - Wave animation

p5.js Effects

Effects marked with (requires p5.js) automatically load the p5.js library when needed.

Advanced Usage

Manual Library Management

import { 
  preloadLibraries, 
  loadVantaEffectFromCdn, 
  getVantaLoadStatus,
  areLibrariesReady 
} from 'vanta-react';

// Preload core libraries
await preloadLibraries();

// Load specific effects
await loadVantaEffectFromCdn('waves');
await loadVantaEffectFromCdn('birds');

// Check status
const status = getVantaLoadStatus();
console.log('Loaded effects:', status.loadedEffects);
console.log('Libraries ready:', areLibrariesReady());

Performance Optimization

import { preloadPopularVantaEffects, loadMultipleVantaEffects } from 'vanta-react';

// Preload popular effects at app startup
useEffect(() => {
  preloadPopularVantaEffects(); // waves, birds, net, clouds, fog
}, []);

// Load multiple effects in parallel
await loadMultipleVantaEffects(['waves', 'birds', 'net']);

Error Boundary Usage

import { ErrorBoundary } from 'vanta-react';

function App() {
  return (
    <ErrorBoundary>
      <Vanta effect="waves" background={true} />
    </ErrorBoundary>
  );
}
}

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import { 
  Vanta, 
  VantaEffectName, 
  VantaProps,
  ErrorBoundary,
  preloadLibraries,
  loadVantaEffectFromCdn,
  type VantaEffect
} from 'vanta-react';

// Type-safe effect selection
const effect: VantaEffectName = 'net';

// Full type support for props
const vantaProps: VantaProps = {
  effect: 'waves',
  background: true,
  style: { borderRadius: '10px' },
  options: {
    color: 0x3f7fb3,
    waveHeight: 20,
  },
  className: 'my-vanta-background',
  onLoadSuccess: () => console.log('Loaded!'),
};

Bundle Size Comparison

| Version | Bundle Size | Description | |---------|-------------|-------------| | v0.2.0 (Local) | ~1.9 MB | Three.js + p5.js bundled | | v0.3.0+ (CDN) | ~18 KB | CDN-optimized with auto-loading | | v0.4.1 (React Fix) | ~20 KB | React 16 compatibility + auto-loading | | v0.4.2 (Current) | ~21 KB | Silent operation + clean console output |

Reduction: 99% smaller bundle size!

CDN URLs Used

// Three.js (v0.134.0 - Vanta.js compatible)
https://cdn.jsdelivr.net/npm/[email protected]/build/three.min.js

// p5.js (v1.1.9 - stable version)
https://cdn.jsdelivr.net/npm/[email protected]/lib/p5.min.js

// Vanta Effects (latest)
https://cdn.jsdelivr.net/npm/vanta@latest/dist/vanta.{effect}.min.js

Migration Guide

From v0.2.0 → v0.3.0

Breaking Changes:

1. Library loading changed from bundled to CDN
2. Manual preloadLibraries() call required

// Before (v0.2.0)
import { Vanta } from 'vanta-react';
function App() {
  return <Vanta effect="waves" />;
}

// After (v0.3.0)
import { Vanta, preloadLibraries } from 'vanta-react';
function App() {
  const [ready, setReady] = useState(false);
  useEffect(() => {
    preloadLibraries().then(() => setReady(true));
  }, []);
  if (!ready) return <div>Loading...</div>;
  return <Vanta effect="waves" />;
}

From v0.3.0 → v0.4.0+ (Current)

New Features:

1. Automatic library loading (no manual setup)
2. Enhanced error handling and retry mechanisms
3. Custom loading/error UI support

// Before (v0.3.0) - Manual preloading
const [ready, setReady] = useState(false);
useEffect(() => {
  preloadLibraries().then(() => setReady(true));
}, []);
if (!ready) return <div>Loading...</div>;
return <Vanta effect="waves" />;

// After (v0.4.0+) - Automatic loading
return <Vanta effect="waves" />; // Just works!

Error Handling

Built-in Error Recovery

// Automatic retry with custom configuration
<Vanta
  effect="net"
  retryCount={5}
  retryDelay={2000}
  onLoadError={(error) => {
    console.error('Loading failed:', error);
    // Send to error tracking service
  }}
/>

Manual Error Handling

import { preloadLibraries, resetPreloadState } from 'vanta-react';

async function handleLibraryError() {
  try {
    await preloadLibraries();
  } catch (error) {
    console.error('CDN load failed:', error);
    
    // Reset and retry
    resetPreloadState();
    await preloadLibraries();
  }
}

Performance Tips

1. Preload Popular Effects

import { preloadPopularVantaEffects } from 'vanta-react';

// Preload common effects at app startup
useEffect(() => {
  preloadPopularVantaEffects(); // waves, birds, net, clouds, fog
}, []);

2. Load Multiple Effects

import { loadMultipleVantaEffects } from 'vanta-react';

// Load specific effects in parallel
await loadMultipleVantaEffects(['waves', 'birds', 'net']);

3. Monitor Performance

import { getVantaLoadStatus } from 'vanta-react';

const status = getVantaLoadStatus();
console.log(`Loaded ${status.loadedCount} effects`);
console.log(`Loading ${status.loadingCount} effects`);

Compatibility

• React: 16.0.0+
• TypeScript: 4.0+
• Three.js: 0.134+ (auto-loaded from CDN)
• p5.js: 1.1.9+ (auto-loaded when needed)
• Node.js: 14+
• Browsers: Modern browsers with ES2015+ support

Development

# Clone repository
git clone https://github.com/gyuha/vanta-react.git
cd vanta-react

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Build
pnpm build

Troubleshooting

Common Issues

1. Blank screen on first load

   • Check browser console for errors
   • Verify CDN accessibility
   • Try disabling ad blockers

2. TypeScript errors

   pnpm add -D @types/react @types/react-dom

3. Effect not rendering

   // Check if libraries are loaded
   import { areLibrariesReady, getPreloadStatus } from 'vanta-react';
      
   console.log('Ready:', areLibrariesReady());
   console.log('Status:', getPreloadStatus());

Contributing

Bug reports, feature requests, and Pull Requests are welcome!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.

Support

• GitHub Issues
• Documentation
• Examples

🚀 Ultra-fast, auto-loading Vanta.js backgrounds for React!
Enjoy minimal bundle sizes and zero-configuration setup with vanta-react v0.4.0+. import { Vanta, VantaEffectName, VantaProps, ErrorBoundary, preloadLibraries, loadVantaEffectFromCdn, type VantaEffectName } from 'vanta-react';

// Type-safe effect selection const effect: VantaEffectName = 'net';

// Full type support const vantaProps: VantaProps = { effect: 'waves', background: true, style: { borderRadius: '10px' }, options: { color: 0x3f7fb3, waveHeight: 20, }, className: 'my-vanta-background', };

## Performance Tips

### 1. Preload Popular Effects

```tsx
import { preloadPopularVantaEffects } from 'vanta-react';

// Preload common effects at app startup
useEffect(() => {
  preloadPopularVantaEffects(); // waves, birds, net, clouds, fog
}, []);

2. Load Multiple Effects

import { loadMultipleVantaEffects } from 'vanta-react';

// Load specific effects in parallel
await loadMultipleVantaEffects(['waves', 'birds', 'net']);

3. Monitor Performance

import { getVantaLoadStatus } from 'vanta-react';

const status = getVantaLoadStatus();
console.log(`Loaded ${status.loadedCount} effects`);
console.log(`Loading ${status.loadingCount} effects`);

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import { 
  Vanta, 
  VantaEffectName, 
  VantaProps,
  ErrorBoundary,
  preloadLibraries,
  loadVantaEffectFromCdn,
  type VantaEffect
} from 'vanta-react';

// Type-safe effect selection
const effect: VantaEffectName = 'net';

// Full type support for props
const vantaProps: VantaProps = {
  effect: 'waves',
  background: true,
  style: { borderRadius: '10px' },
  options: {
    color: 0x3f7fb3,
    waveHeight: 20,
  },
  className: 'my-vanta-background',
  onLoadSuccess: () => console.log('Loaded!'),
};

CDN URLs Used

// Three.js (v0.134.0 - Vanta.js compatible)
https://cdn.jsdelivr.net/npm/[email protected]/build/three.min.js

// p5.js (v1.1.9 - stable version)
https://cdn.jsdelivr.net/npm/[email protected]/lib/p5.min.js

// Vanta Effects (latest)
https://cdn.jsdelivr.net/npm/vanta@latest/dist/vanta.{effect}.min.js

Compatibility

• React: 16.0.0+
• Three.js: 0.134+ (loaded from CDN)
• p5.js: 1.1.9+ (loaded from CDN when needed)
• TypeScript: 4.0+
• Node.js: 14+
• Browsers: Modern browsers with ES2015+ support

Development

# Clone repository
git clone https://github.com/gyuha/vanta-react.git
cd vanta-react

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Start CDN demo
pnpm demo:cdn

# Build
pnpm build

License

MIT License - see LICENSE file for details.

Support

• GitHub Issues
• Documentation
• Examples

🚀 Ultra-fast, auto-loading Vanta.js backgrounds for React!