dotLottie Web Player Performance Optimization

The dotLottie Web Player provides several features and configuration options to optimize animation performance. This guide covers best practices and techniques for achieving optimal playback performance.

Render Configuration

Device Pixel Ratio

Control rendering resolution based on device capabilities:

const dotLottie = new DotLottie({
  canvas: document.querySelector("#canvas"),
  src: "animation.lottie",
  renderConfig: {
    // Automatically adjusted for high-DPI displays
    devicePixelRatio: window.devicePixelRatio * 0.75,
  },
});

Frame Interpolation

Control frame interpolation for performance vs. smoothness:

const dotLottie = new DotLottie({
  canvas: document.querySelector("#canvas"),
  src: "animation.lottie",
  useFrameInterpolation: false, // Disable for better performance
});

Offscreen Optimization

Automatically pause animations when not visible:

const dotLottie = new DotLottie({
  canvas: document.querySelector("#canvas"),
  src: "animation.lottie",
  renderConfig: {
    freezeOnOffscreen: true,
  },
});

Web Worker Usage

Offload rendering to a separate thread:

import { DotLottieWorker } from "@lottiefiles/dotlottie-web";

const animation = new DotLottieWorker({
  canvas: document.querySelector("#canvas"),
  src: "animation.lottie",
  autoplay: true,
  workerId: "worker-1",
});

Memory Management

Resource Cleanup

// Clean up when animation is no longer needed
dotLottie.destroy();

// Remove event listeners
dotLottie.removeEventListener("frame", frameHandler);
dotLottie.removeEventListener("loop", loopHandler);

Multiple Animations

When working with multiple animations:

const animations = [];

// Group animations by worker
function createAnimation(src, workerId) {
  const animation = new DotLottieWorker({
    canvas: document.querySelector(`#canvas-${workerId}`),
    src: src,
    workerId: workerId,
    renderConfig: {
      freezeOnOffscreen: true,
      devicePixelRatio: window.devicePixelRatio * 0.75,
    },
  });

  animations.push(animation);
}

// Clean up all animations
function cleanup() {
  animations.forEach((animation) => animation.destroy());
  animations.length = 0;
}

Best Practices

1. Canvas Management

Use appropriate canvas sizes
Implement responsive scaling
Handle resize events efficiently:

const dotLottie = new DotLottie({
  canvas: document.querySelector("#canvas"),
  src: "animation.lottie",
  renderConfig: {
    autoResize: true, // Automatic canvas resizing
  },
});

// Or handle manually if needed
window.addEventListener("resize", () => {
  requestAnimationFrame(() => {
    dotLottie.resize();
  });
});

2. Animation Loading

Load animations only when needed
Implement lazy loading for off-screen animations
Consider preloading critical animations

// Lazy loading example
const observer = new IntersectionObserver((entries) => {
  entries.forEach((entry) => {
    if (entry.isIntersecting) {
      loadAnimation(entry.target);
      observer.unobserve(entry.target);
    }
  });
});

function loadAnimation(container) {
  const canvas = container.querySelector("canvas");
  new DotLottie({
    canvas: canvas,
    src: canvas.dataset.animation,
    autoplay: true,
    renderConfig: {
      freezeOnOffscreen: true,
    },
  });
}

// Observe animation containers
document.querySelectorAll(".animation-container").forEach((container) => {
  observer.observe(container);
});

3. Rendering Optimization

Use appropriate fit modes
Optimize for device pixel ratio
Consider frame interpolation trade-offs

const dotLottie = new DotLottie({
  canvas: document.querySelector("#canvas"),
  src: "animation.lottie",
  renderConfig: {
    devicePixelRatio: Math.min(window.devicePixelRatio, 2), // Cap at 2x
    freezeOnOffscreen: true,
  },
  useFrameInterpolation: false, // Disable for high-performance needs
  layout: {
    fit: "contain", // Use appropriate fit mode
  },
});

Performance Monitoring

Monitor animation performance:

let lastFrame = performance.now();
let frameCount = 0;

dotLottie.addEventListener("frame", () => {
  frameCount++;
  const now = performance.now();
  if (now - lastFrame >= 1000) {
    console.log(`FPS: ${frameCount}`);
    frameCount = 0;
    lastFrame = now;
  }
});

Common Issues and Solutions

High CPU Usage
- Use Web Workers for complex animations
- Implement proper cleanup
- Monitor animation complexity
Memory Leaks
- Destroy animations when not needed
- Remove event listeners
- Clear references to unused objects
Poor Mobile Performance
- Optimize device pixel ratio
- Disable frame interpolation
- Use appropriate canvas sizes