AURORA_COMPONENT.md

Component documentation for the Aurora visual effects component.

Overview

The Aurora component creates animated WebGL-based aurora effects using the OGL (OpenGL) library. It provides customizable, performant visual effects suitable for backgrounds, loading states, or decorative elements.

Component Location

• File: src/components/Aurora.tsx
• Type: Visual Effects Component
• Framework: React with TypeScript + WebGL

Features

• WebGL Rendering: Hardware-accelerated graphics using OGL library
• Customizable Colors: Multi-stop color gradients with smooth transitions
• Dynamic Animation: Real-time noise-based movement and morphing
• Performance Optimized: Efficient rendering with minimal CPU overhead
• Responsive Design: Automatically adapts to container size changes
• Configurable Parameters: Amplitude, blend, speed, and opacity controls
• Transparent Background: Supports overlay on existing content

Props Interface

interface AuroraProps {
  colorStops?: string[];        // Gradient color array (default: ["#FF9966", "#FFD93D", "#FF6B6B"])
  amplitude?: number;           // Wave amplitude (default: 0.2)
  blend?: number;              // Edge blending (default: 0.9)
  speed?: number;              // Animation speed multiplier
  time?: number;               // Manual time control
  opacity?: number;            // Component opacity (default: 0.4)
}

Usage Examples

Basic Implementation

import Aurora from '@/components/Aurora';

function BackgroundEffect() {
  return (
    <div className="relative min-h-screen">
      <Aurora />
      <div className="relative z-10">
        {/* Content overlay */}
      </div>
    </div>
  );
}

Custom Color Scheme

<Aurora
  colorStops={["#4F46E5", "#7C3AED", "#EC4899"]}
  amplitude={0.3}
  blend={0.8}
  opacity={0.6}
/>

Loading State Effect

function LoadingScreen() {
  return (
    <div className="fixed inset-0 flex items-center justify-center">
      <Aurora
        colorStops={["#10B981", "#3B82F6", "#8B5CF6"]}
        speed={2}
        amplitude={0.15}
      />
      <div className="relative z-10 text-white text-xl">Loading...</div>
    </div>
  );
}

Subtle Background

<Aurora
  colorStops={["#F3F4F6", "#E5E7EB", "#D1D5DB"]}
  amplitude={0.1}
  blend={0.95}
  speed={0.5}
  opacity={0.2}
/>

Shader Implementation

The Aurora effect is created using custom GLSL shaders:

Vertex Shader

#version 300 es
in vec2 position;
void main() {
  gl_Position = vec4(position, 0.0, 1.0);
}

Fragment Shader

#version 300 es
precision highp float;

uniform float uTime;
uniform float uAmplitude;
uniform vec3 uColorStops[3];
uniform vec2 uResolution;
uniform float uBlend;

out vec4 fragColor;

// Simplex noise implementation for organic movement
float snoise(vec2 v) {
  // ... noise calculation
}

void main() {
  vec2 uv = gl_FragCoord.xy / uResolution;
  
  // Create color gradient
  ColorStop colors[3];
  colors[0] = ColorStop(uColorStops[0], 0.0);
  colors[1] = ColorStop(uColorStops[1], 0.5);
  colors[2] = ColorStop(uColorStops[2], 1.0);
  
  // Generate aurora wave pattern
  float height = snoise(vec2(uv.x * 2.0 + uTime * 0.1, uTime * 0.25)) * 0.5 * uAmplitude;
  height = exp(height);
  height = (uv.y * 2.0 - height + 0.2);
  
  // Apply blending and transparency
  float intensity = 0.6 * height;
  float midPoint = 0.20;
  float auroraAlpha = smoothstep(midPoint - uBlend * 0.5, midPoint + uBlend * 0.5, intensity);
  
  fragColor = vec4(intensity * rampColor * auroraAlpha, auroraAlpha);
}

WebGL Setup and Configuration

Renderer Initialization

const renderer = new Renderer({
  alpha: true,
  premultipliedAlpha: true,
  antialias: true
});

const gl = renderer.gl;
gl.clearColor(0, 0, 0, 0);
gl.enable(gl.BLEND);
gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
gl.canvas.style.backgroundColor = 'transparent';

Geometry and Program Setup

const geometry = new Triangle(gl);
if (geometry.attributes.uv) {
  delete geometry.attributes.uv; // Remove unused UV coordinates
}

const program = new Program(gl, {
  vertex: VERT,
  fragment: FRAG,
  uniforms: {
    uTime: { value: 0 },
    uAmplitude: { value: amplitude },
    uColorStops: { value: colorStopsArray },
    uResolution: { value: [width, height] },
    uBlend: { value: blend }
  }
});

Animation Loop

Real-time Updates

const update = (t: number): void => {
  animateId = requestAnimationFrame(update);
  
  // Get current props for dynamic updates
  const { time = t * 0.01, speed = 0.3 } = propsRef.current;
  
  // Update shader uniforms
  program.uniforms.uTime.value = time * speed * 0.1;
  program.uniforms.uAmplitude.value = propsRef.current.amplitude ?? amplitude;
  program.uniforms.uBlend.value = propsRef.current.blend ?? blend;
  
  // Update colors if changed
  const stops = propsRef.current.colorStops ?? colorStops;
  program.uniforms.uColorStops.value = stops.map((color: string) => {
    const c = new Color(color);
    return [c.r, c.g, c.b];
  });
  
  // Render the frame
  renderer.render({ scene: mesh });
};

Responsive Behavior

Window Resize Handling

function resize(): void {
  if (!ctn) return;
  const width = ctn.offsetWidth;
  const height = ctn.offsetHeight;
  
  renderer.setSize(width, height);
  if (program) {
    program.uniforms.uResolution.value = [width, height];
  }
}

window.addEventListener("resize", resize);

Color Management

Color Stop Processing

const colorStopsArray = colorStops.map((color: string) => {
  const c = new Color(color);
  return [c.r, c.g, c.b]; // RGB values 0-1
});

// Dynamic color updates
const stops = propsRef.current.colorStops ?? colorStops;
program.uniforms.uColorStops.value = stops.map((color: string) => {
  const c = new Color(color);
  return [c.r, c.g, c.b];
});

Performance Considerations

Optimization Strategies

• GPU Acceleration: All rendering happens on GPU via WebGL
• Minimal CPU Usage: Efficient animation loop with RAF
• Memory Management: Proper cleanup of WebGL resources
• Responsive Updates: Only resize when container dimensions change

Resource Cleanup

return () => {
  cancelAnimationFrame(animateId);
  window.removeEventListener("resize", resize);
  
  if (ctn && gl.canvas.parentNode === ctn) {
    ctn.removeChild(gl.canvas);
  }
  
  // Force WebGL context loss to free GPU memory
  gl.getExtension("WEBGL_lose_context")?.loseContext();
};

Styling Integration

CSS Container

<div 
  ref={ctnDom} 
  className="aurora-container" 
  style={{opacity: opacity }}
/>

CSS Classes (Aurora.css)

.aurora-container {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  pointer-events: none; /* Allow clicks to pass through */
  overflow: hidden;
}

Browser Compatibility

WebGL Support Detection

// The component gracefully handles WebGL unavailability
// OGL library provides fallbacks for unsupported browsers

Performance Considerations by Device

• Desktop: Full quality rendering
• Mobile: Automatic performance scaling
• Low-end Devices: Graceful degradation

Common Use Cases

Background Effects

// Subtle background for login pages
<Aurora
  colorStops={["#EEF2FF", "#E0E7FF", "#C7D2FE"]}
  amplitude={0.1}
  opacity={0.3}
/>

Loading Animations

// Dynamic loading indicator
<Aurora
  colorStops={["#059669", "#0891B2", "#7C3AED"]}
  speed={1.5}
  amplitude={0.25}
/>

Hero Sections

// Eye-catching hero background
<Aurora
  colorStops={["#FF6B6B", "#4ECDC4", "#45B7D1"]}
  amplitude={0.4}
  blend={0.7}
  opacity={0.8}
/>

Dependencies

Core Libraries

• OGL: Lightweight WebGL library
  • Renderer - WebGL rendering context
  • Program - Shader program management
  • Mesh - Geometry rendering
  • Color - Color utilities
  • Triangle - Full-screen triangle geometry

Styling

• @/styles/Aurora.css - Component-specific styles

React Integration

• React hooks for lifecycle management
• Ref management for DOM integration
• Props handling for dynamic updates

Accessibility Considerations

• Motion Sensitivity: Consider prefers-reduced-motion CSS queries
• Performance Impact: Minimal for modern devices
• Screen Readers: Component is purely decorative (hidden from assistive technology)

Troubleshooting

Common Issues

1. WebGL Context Loss: Handled automatically with cleanup
2. Performance on Mobile: Reduced automatically by browser
3. Color Format Issues: Use hex strings for best compatibility

Debug Mode

// Enable WebGL debugging in development
if (process.env.NODE_ENV === 'development') {
  console.log('Aurora WebGL context:', gl);
}

Related Components

• Background and layout components
• Loading and transition effects
• Decorative visual elements
• Animated UI components