dotLottie Player Web Worker Support

The dotLottie Web Player provides the DotLottieWorker class to offload animation rendering to a dedicated Web Worker↗, significantly improving application performance by freeing the main thread from rendering tasks.

Basic Usage

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

const animation = new DotLottieWorker({
  canvas: document.getElementById("canvas"),
  src: "url/to/animation.json",
  autoplay: true,
  loop: true,
});

Worker Grouping

By default, all animations using DotLottieWorker share the same worker. You can distribute workload across multiple workers using the workerId property:

const animation1 = new DotLottieWorker({
  canvas: document.getElementById("canvas"),
  src: "url/to/animation.json",
  autoplay: true,
  loop: true,
  workerId: "worker-1",
});

const animation2 = new DotLottieWorker({
  canvas: document.getElementById("canvas-2"),
  src: "url/to/animation2.json",
  autoplay: true,
  loop: true,
  workerId: "worker-2",
});

This feature is particularly useful when rendering multiple animations simultaneously, allowing you to distribute the rendering workload for optimal performance.

API

DotLottieWorker provides the same API as DotLottie, with the key difference that all methods execute in the worker thread and return a Promise.

Example:

const dotLottie = new DotLottieWorker({
  canvas: document.getElementById("canvas"),
  src: "url/to/animation.json",
  autoplay: true,
  loop: true,
});

dotLottie.play().then(() => {
  console.log("Animation started");
});

Constructor

The DotLottieWorker constructor accepts the same configuration object as DotLottie, plus the optional workerId property:

const animation = new DotLottieWorker({
  canvas: document.getElementById("canvas"),
  src: "url/to/animation.json",
  autoplay: true,
  loop: true,
  workerId: "worker-1", // Optional worker group identifier
});

Properties and Methods

All properties and methods from the standard DotLottie class are available, but they return Promises when accessed:

// Properties
const isPlaying = await dotLottie.isPlaying;
const currentFrame = await dotLottie.currentFrame;

// Methods
await dotLottie.play();
await dotLottie.pause();
await dotLottie.stop();

Events

Event handling remains the same as the standard player:

dotLottie.addEventListener("play", () => {
  console.log("Animation started playing");
});

dotLottie.addEventListener("complete", () => {
  console.log("Animation completed");
});

Performance Comparison

CodePen↗

Using Web Workers can significantly improve performance, especially when:

Running multiple complex animations
Dealing with high frame rates
Managing CPU-intensive animations
Working with large animation files

Example performance optimization:

// Group related animations in the same worker
const backgroundAnimations = ["bg1.json", "bg2.json"].map(
  (src) =>
    new DotLottieWorker({
      canvas: document.getElementById(src),
      src: src,
      workerId: "background",
      renderConfig: {
        freezeOnOffscreen: true,
      },
    })
);

// Use separate worker for interactive animations
const interactiveAnimation = new DotLottieWorker({
  canvas: document.getElementById("interactive"),
  src: "interactive.json",
  workerId: "interactive",
});

Best Practices

Worker Distribution
- Group related animations in the same worker
- Use separate workers for independent animation groups
- Consider device capabilities when creating workers
Resource Management
- Clean up workers when animations are no longer needed
- Monitor worker performance
- Use freezeOnOffscreen for better resource utilization
Error Handling
- Handle promise rejections from worker methods
- Implement fallback to main thread if worker creation fails
- Monitor worker health and restart if necessary