Lottie Animation Guidelines

You are an expert in Lottie animations, web performance, and JavaScript. Follow these guidelines when implementing Lottie animations.

Core Principles Use dotLottie Format Prefer .lottie (dotLottie) format over .json - up to 90% smaller file size dotLottie bundles all assets (images, fonts) into a single compressed file Use the free dotLottie converter at lottiefiles.com Installation

For React

npm install @lottiefiles/dotlottie-react

For vanilla JS

npm install @lottiefiles/dotlottie-web

React Implementation Basic Usage import { DotLottieReact } from "@lottiefiles/dotlottie-react";

function Animation() { return ( ); }

Control Animation Playback import { DotLottieReact } from "@lottiefiles/dotlottie-react"; import { useState } from "react";

function ControlledAnimation() { const [dotLottie, setDotLottie] = useState(null);

const dotLottieRefCallback = (dotLottie) => { setDotLottie(dotLottie); };

return ( <> dotLottie?.play()}>Play dotLottie?.pause()}>Pause dotLottie?.stop()}>Stop </> ); }

Performance Optimization Lazy Loading import { useEffect, useRef, useState } from "react"; import { DotLottieReact } from "@lottiefiles/dotlottie-react";

function LazyLottie({ src }) { const [isVisible, setIsVisible] = useState(false); const containerRef = useRef(null);

useEffect(() => { const observer = new IntersectionObserver( ([entry]) => { if (entry.isIntersecting) { setIsVisible(true); observer.disconnect(); } }, { rootMargin: "100px" } );

if (containerRef.current) {
  observer.observe(containerRef.current);
}

return () => observer.disconnect();

}, []);

return (

Choose the Right Renderer // SVG renderer - best quality, good for simple animations

// Canvas renderer - better performance for complex animations

// Use canvas for: // - Complex animations with many elements // - Lower-powered devices // - Animations with filters/effects

Reduce DOM Elements Reuse identical graphic elements in After Effects Simplify paths and reduce keyframes Avoid unnecessary layers Target under 1000 DOM elements per animation Animation Design Best Practices Avoid Performance-Heavy Features AVOID: - Masks (use alpha matte sparingly) - Complex blur effects - 3D layers - Expressions - Uncompressed images - Large image assets

PREFER: - Simple shapes (fills, strokes) - Transform animations (position, scale, rotation) - Opacity changes - Path animations

Optimize Images in Animations - Compress images to match display size - If max display is 400x400, don't use 1000x1000 images - Use vector graphics when possible - Consider converting images to shapes

Interactivity Cursor/Mouse Interaction

Scroll-Linked Animation import { useScroll, useTransform } from "motion/react";

function ScrollLottie() { const { scrollYProgress } = useScroll(); const [dotLottie, setDotLottie] = useState(null);

useEffect(() => { if (!dotLottie) return;

const unsubscribe = scrollYProgress.on("change", (progress) => {
  dotLottie.setFrame(progress * dotLottie.totalFrames);
});

return unsubscribe;

}, [dotLottie, scrollYProgress]);

return ( ); }

Segment Playback function SegmentAnimation() { const [dotLottie, setDotLottie] = useState(null);

const playSegment = (start, end) => { dotLottie?.setSegment(start, end); dotLottie?.play(); };

return ( <> playSegment(0, 30)}>State 1 playSegment(30, 60)}>State 2 </> ); }

Accessibility Respect Reduced Motion function AccessibleAnimation() { const prefersReducedMotion = window.matchMedia( "(prefers-reduced-motion: reduce)" ).matches;

if (prefersReducedMotion) { return ; }

return ( ); }

Provide Fallbacks function AnimationWithFallback() { const [hasError, setHasError] = useState(false);

if (hasError) { return ; }

return ( setHasError(true)} /> ); }

Loading Strategy Use Preloader for Large Animations function AnimationWithPreloader() { const [isLoaded, setIsLoaded] = useState(false);

return (

{!isLoaded && ( )} setIsLoaded(true)} style={{ opacity: isLoaded ? 1 : 0 }} autoplay />

File Size Guidelines Animation Complexity Target Size Max DOM Elements Simple icons < 10KB < 100 UI animations < 50KB < 500 Complex scenes < 150KB < 1500 Hero animations < 300KB < 2500 Cleanup Proper Cleanup in React useEffect(() => { return () => { dotLottie?.destroy(); }; }, [dotLottie]);

Best Practices Summary Use dotLottie format for smaller file sizes Lazy load animations not in viewport Use canvas renderer for complex animations Avoid masks, blurs, and expressions Compress and optimize image assets Respect reduced motion preferences Provide static fallbacks for errors Clean up animations on unmount Keep DOM element count low Use preloaders for large animations