The Complete Production SOP: How to Deploy and Run Lottie-Web JSON Vector Animation Engine in Autonomous AI Agents

---
name: "lottie-web-vector-animations"
description: "Render lightweight, scalable After Effects vector animations on the web with Lottie."
metadata:
  author: "Airbnb"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "play lottie animation react"
  - "trigger lottie on hover"
  - "scrub lottie on scroll"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# Lottie-Web JSON Vector Animation Engine

Embeds Bodymovin JSON animation files using lottie-web / @lottiefiles/react-lottie-player: canvas/SVG renderers, frame markers, scroll scrubbing, and interactive hover triggers.

## Execution SOP & Rules
1. Prefer renderer: 'svg' for crisp vector shapes; use renderer: 'canvas' for complex particle scenes.
2. Pause animations when off-screen using IntersectionObserver to conserve mobile CPU cycles.
3. Trigger specific animation segments using animationInstance.playSegments([startFrame, endFrame], true).
4. Destroy animation instances with animationInstance.destroy() during component teardown.

{
  "dependencies": {
    "lottie-web": "^5.12.2",
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  },
  "devDependencies": {
    "@types/lottie-web": "^5.12.0",
    "typescript": "^5.4.5"
  }
}

"use client";

import React, { useEffect, useRef } from "react";
import lottie, { AnimationItem } from "lottie-web";

interface LottiePlayerProps {
  animationPath: string;
  loop?: boolean;
  autoplay?: boolean;
  hoverTrigger?: boolean;
  className?: string;
}

export const LottieInteractivePlayer: React.FC<LottiePlayerProps> = ({
  animationPath,
  loop = false,
  autoplay = false,
  hoverTrigger = false,
  className = "w-64 h-64",
}) => {
  const containerRef = useRef<HTMLDivElement | null>(null);
  const animInstanceRef = useRef<AnimationItem | null>(null);

  useEffect(() => {
    if (!containerRef.current) return;

    // Initialize Lottie
    const anim = lottie.loadAnimation({
      container: containerRef.current,
      renderer: "svg",
      loop,
      autoplay,
      path: animationPath,
    });
    animInstanceRef.current = anim;

    // IntersectionObserver to pause off-screen rendering
    const observer = new IntersectionObserver(([entry]) => {
      if (!animInstanceRef.current) return;
      if (entry.isIntersecting) {
        if (autoplay) animInstanceRef.current.play();
      } else {
        animInstanceRef.current.pause();
      }
    }, { threshold: 0.1 });

    observer.observe(containerRef.current);

    return () => {
      observer.disconnect();
      anim.destroy();
      animInstanceRef.current = null;
    };
  }, [animationPath, loop, autoplay]);

  const handleMouseEnter = () => {
    if (hoverTrigger && animInstanceRef.current) {
      animInstanceRef.current.setDirection(1);
      animInstanceRef.current.play();
    }
  };

  const handleMouseLeave = () => {
    if (hoverTrigger && animInstanceRef.current) {
      animInstanceRef.current.setDirection(-1);
      animInstanceRef.current.play();
    }
  };

  return (
    <div
      ref={containerRef}
      className={className}
      onMouseEnter={handleMouseEnter}
      onMouseLeave={handleMouseLeave}
      aria-hidden="true"
    />
  );
};

import { render, screen } from "@testing-library/react";
import { describe, it, expect, vi } from "vitest";
import { LottieInteractivePlayer } from "../LottieInteractivePlayer";
import lottie from "lottie-web";

vi.mock("lottie-web", () => ({
  default: {
    loadAnimation: vi.fn().mockReturnValue({
      destroy: vi.fn(),
      play: vi.fn(),
      pause: vi.fn(),
      setDirection: vi.fn(),
    }),
  },
}));

describe("LottieInteractivePlayer", () => {
  it("initializes and destroys lottie instance on unmount", () => {
    const { unmount } = render(
      <LottieInteractivePlayer animationPath="/animations/test.json" />
    );
    expect(lottie.loadAnimation).toHaveBeenCalledTimes(1);
    unmount();
    const animInstance = vi.mocked(lottie.loadAnimation).mock.results[0].value;
    expect(animInstance.destroy).toHaveBeenCalledTimes(1);
  });
});