ntroller accepts a renderer configuration (svg or canvas). SVG is default for UI components; canvas is enforced for particle effects or illustrations exceeding 50 layers. 3. Explicit Lifecycle Binding: React's useEffect cleanup function directly invokes the engine's destruction method, guaranteeing memory release on unmount. 4. State Synchronization: Playback state is managed through React state rather than direct DOM manipulation, ensuring predictable re-renders and compatibility with concurrent features.

Implementation

The following TypeScript implementation wraps the underlying animation engine behind a consistent interface. It demonstrates lazy loading, renderer configuration, and playback control.

import { useEffect, useRef, useState, useCallback } from 'react';

type AnimationRenderer = 'svg' | 'canvas';
type PlaybackState = 'idle' | 'playing' | 'paused' | 'completed';

interface AnimationConfig {
  src: string;
  renderer?: AnimationRenderer;
  loop?: boolean;
  autoplay?: boolean;
  speed?: number;
}

export function useAnimationRuntime(config: AnimationConfig) {
  const containerRef = useRef<HTMLDivElement | null>(null);
  const engineRef = useRef<any>(null);
  const [state, setState] = useState<PlaybackState>('idle');
  const [error, setError] = useState<string | null>(null);

  const initializeEngine = useCallback(async () => {
    if (!containerRef.current) return;

    try {
      const response = await fetch(config.src);
      if (!response.ok) throw new Error(`Failed to load animation: ${config.src}`);
      
      const payload = await response.json();
      
      // Dynamic import prevents static bundling
      const lottieModule = await import('lottie-web');
      const engine = lottieModule.default;

      const instance = engine.loadAnimation({
        container: containerRef.current,
        renderer: config.renderer || 'svg',
        loop: config.loop ?? false,
        autoplay: config.autoplay ?? false,
        animationData: payload,
      });

      engineRef.current = instance;

      // Sync playback state with React
      instance.addEventListener('complete', () => setState('completed'));
      instance.addEventListener('loopComplete', () => setState('playing'));
      
      if (config.speed) {
        instance.setSpeed(config.speed);
      }

      setState(config.autoplay ? 'playing' : 'idle');
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Unknown animation error');
    }
  }, [config]);

  useEffect(() => {
    initializeEngine();

    return () => {
      if (engineRef.current) {
        engineRef.current.destroy();
        engineRef.current = null;
      }
      setState('idle');
    };
  }, [initializeEngine]);

  const controls = {
    play: () => engineRef.current?.play(),
    pause: () => engineRef.current?.pause(),
    setSpeed: (rate: number) => engineRef.current?.setSpeed(rate),
    goToFrame: (frame: number, stop: boolean = true) => {
      engineRef.current?.goToAndStop(frame, stop);
    },
    playSegment: (start: number, end: number) => {
      engineRef.current?.playSegments([start, end], true);
    },
  };

  return { containerRef, state, error, controls };
}

Component Wrapper

import React from 'react';
import { useAnimationRuntime } from './useAnimationRuntime';

interface VectorMotionProps {
  source: string;
  width?: number;
  height?: number;
  renderer?: 'svg' | 'canvas';
  loop?: boolean;
  autoStart?: boolean;
}

export const VectorMotion: React.FC<VectorMotionProps> = ({
  source,
  width = 200,
  height = 200,
  renderer = 'svg',
  loop = false,
  autoStart = false,
}) => {
  const { containerRef, state, error, controls } = useAnimationRuntime({
    src: source,
    renderer,
    loop,
    autoplay: autoStart,
  });

  if (error) {
    return <div role="alert" style={{ color: 'red' }}>Animation failed: {error}</div>;
  }

  return (
    <div
      ref={containerRef}
      style={{ width, height, position: 'relative' }}
      aria-hidden={state === 'idle'}
    />
  );
};

Why this structure works: The hook isolates engine initialization and cleanup, preventing memory leaks during hot module replacement or route transitions. Dynamic fetch() + import() ensures the animation payload and engine library are only loaded when the component mounts. State synchronization allows parent components to trigger conditional playback (e.g., play only when a modal opens) without direct DOM manipulation.

Pitfall Guide

1. Static JSON Bundling

Explanation: Importing .json files directly into components forces the bundler to inline the payload into the main JavaScript chunk. This increases initial download size and forces synchronous parsing during hydration. Fix: Always load animations via fetch() or dynamic import(). Host assets on a CDN with aggressive caching headers to leverage browser HTTP/2 multiplexing.

2. Renderer Mismatch

Explanation: Using the SVG renderer for complex illustrations with 50+ layers generates thousands of DOM nodes. This triggers excessive layout recalculations and GPU compositing overhead. Fix: Switch to the canvas renderer for particle effects, gradients, or multi-layer compositions. Reserve SVG for simple icons, loaders, and UI state indicators where CSS styling or accessibility inspection is required.

3. Missing Unmount Cleanup

Explanation: Failing to call the engine's destruction method leaves active animation frames and event listeners attached to detached DOM nodes. This causes memory leaks and cumulative performance degradation in single-page applications. Fix: Always invoke .destroy() inside the useEffect cleanup function. Verify cleanup execution using React DevTools Profiler or browser memory snapshots.

4. Main-Thread Blocking on Large Payloads

Explanation: Parsing uncompressed JSON files exceeding 100KB blocks the main thread, delaying user input and causing frame drops. Fix: Migrate to the .lottie compressed format. The archive structure enables Web Worker-based decompression, shifting parsing off the main thread and reducing load times by ~80%.

5. Hardcoded Container Dimensions

Explanation: Setting fixed pixel dimensions on the animation container breaks responsive layouts and causes aspect ratio distortion on different viewports. Fix: Use CSS aspect-ratio or container queries. Pass dimensions as props but enforce proportional scaling via width: 100%; height: auto; on the internal canvas/SVG element.

6. Accessibility Neglect

Explanation: Vector animations are decorative by default but can confuse screen readers if not properly marked. Unlabeled animations may be announced as empty or generic divs. Fix: Apply aria-hidden="true" to decorative animations. For functional animations (e.g., loading states), pair the component with aria-live="polite" and descriptive text that updates based on playback state.

7. Direct DOM Manipulation for Playback

Explanation: Calling engine methods directly from event handlers bypasses React's rendering cycle, causing state drift between the UI and the animation controller. Fix: Expose playback controls through a React state manager or context. Trigger playback changes via state updates, allowing React to batch updates and maintain predictable component lifecycles.

Production Bundle

Action Checklist

• Replace static .json imports with dynamic fetch() or CDN-hosted assets
• Migrate legacy animations to .lottie compressed format for Web Worker parsing
• Configure renderer type based on layer complexity (SVG for UI, Canvas for effects)
• Implement explicit .destroy() cleanup in useEffect return functions
• Add aria-hidden or aria-live attributes based on animation purpose
• Wrap playback controls in React state to prevent direct DOM manipulation
• Monitor INP and memory usage using Performance tab after integration
• Provide static fallback images for environments with disabled JavaScript

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Simple UI icon or button state	SVG Renderer + .lottie format	Maintains crispness, allows CSS styling, minimal DOM overhead	Low
Complex loading spinner with gradients	Canvas Renderer + .lottie format	Bypasses DOM layout, handles gradients efficiently	Low-Medium
Background hero animation	Canvas Renderer + Lazy Fetch	Prevents main-thread blocking, reduces initial bundle size	Medium
Email or static platform export	Convert to GIF/MP4/WebP	Vector engines unsupported in email clients; raster ensures compatibility	None (build-time)
High-frequency state toggling	SVG Renderer + React State Sync	DOM updates are predictable; avoids canvas redraw latency	Low

Configuration Template

Copy this configuration into your project's animation utility directory. It establishes a standardized loading pipeline with error boundaries and performance monitoring.

// animation.config.ts
export const ANIMATION_PRESETS = {
  ui_icon: {
    renderer: 'svg' as const,
    loop: false,
    autoplay: false,
    preload: false,
  },
  loader: {
    renderer: 'svg' as const,
    loop: true,
    autoplay: true,
    preload: true,
  },
  complex_scene: {
    renderer: 'canvas' as const,
    loop: true,
    autoplay: false,
    preload: false,
  },
};

// performance.monitor.ts
export function trackAnimationLoad(assetUrl: string, duration: number) {
  if (typeof window !== 'undefined' && window.performance) {
    window.performance.mark(`animation-load-${assetUrl}`);
    window.performance.measure('animation-load-duration', `animation-load-${assetUrl}`);
  }
  console.debug(`[Animation] Loaded ${assetUrl} in ${duration}ms`);
}

Quick Start Guide

1. Install dependencies: Run npm install lottie-web @lottiefiles/dotlottie-react to cover both legacy and modern formats.
2. Host assets externally: Place .json or .lottie files in your public directory or upload them to a CDN. Never commit them to your source tree.
3. Initialize the hook: Import useAnimationRuntime into your component, pass the asset URL, and attach containerRef to a div.
4. Configure renderer: Set renderer: 'canvas' for complex illustrations, or leave as default SVG for UI elements.
5. Verify cleanup: Open browser DevTools, navigate away from the component, and confirm that animation frames and memory allocations drop to baseline.