dotLottie Web Documentation

@lottiefiles/dotlottie-web is an isomorphic JavaScript library used for rendering Lottie and dotLottie animations in both web browsers and Node.js environments. It provides an API for loading, playing, and controlling animations, with support for advanced features like interactivity and theming.

What is dotLottie?

dotLottie is an open-source file format that bundles one or more Lottie animations and their assets into a single, compressed .lottie file using ZIP compression. This format is more efficient for storage and distribution and supports advanced features like interactivity and theming.

For complex animations, multiple simultaneous animations, or to keep the main thread free for UI interactions, use DotLottieWorker. This offloads rendering to a Web Worker.

• Performance: Recommended for mobile devices and heavy JS environments.
• Worker Grouping: Use the workerId option to group animations into separate workers. By default, all instances share the same worker.
• React Support: Use DotLottieWorkerReact from @lottiefiles/dotlottie-react for a component-based approach with workers.

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

// Dedicated worker for hero animation
const heroAnimation = new DotLottieWorker({
  canvas: heroCanvas,
  src: 'hero.lottie',
  workerId: 'hero-worker',
});

A single .lottie file can contain multiple animations. You can access the list of animations via the manifest property and switch between them using loadAnimation(id).

// Get all animation IDs from the manifest
const animations = dotLottie.manifest?.animations;
// Returns: [{ id: 'animation-1' }, { id: 'animation-2' }]

// Load a specific animation by its ID
dotLottie.loadAnimation('animation-2');

The player supports three rendering backends. While the default is Software (Canvas2D), you can opt into hardware-accelerated rendering by changing your import path. The DotLottie class and its API remain identical across all backends.

// WebGL2 — broadly supported
import { DotLottie } from '@lottiefiles/dotlottie-web/webgl';

// WebGPU — experimental, modern Chromium / Safari TP
import { DotLottie } from '@lottiefiles/dotlottie-web/webgpu';

Use DotLottieWorker to offload animation rendering to a Web Worker. This keeps the main thread free for UI interactions, which is critical for complex animations, multiple simultaneous animations, or mobile devices.

By default, all DotLottieWorker instances share the same worker. You can group animations into separate workers by providing a unique workerId.

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

// Basic Worker Usage
const dotLottie = new DotLottieWorker({
  canvas: document.getElementById('canvas') as HTMLCanvasElement,
  src: 'https://example.com/animation.lottie',
  autoplay: true,
  loop: true,
});

// Worker Grouping
const heroAnimation = new DotLottieWorker({
  canvas: heroCanvas,
  src: 'hero.lottie',
  workerId: 'hero-worker',
});

dotLottie v2 supports state machines defined directly within the .lottie file. You can drive these animations by specifying a stateMachineId during initialization. The player emits typed events like stateMachineStart, stateMachineTransition, and stateMachineStateEntered to allow you to sync your application logic with the animation state.

const dotLottie = new DotLottie({
  canvas: document.getElementById('canvas'),
  src: 'interactive-button.lottie',
  stateMachineId: 'main',
  autoplay: true,
});

Select a package based on your project requirements:

• @lottiefiles/dotlottie-web: Use for framework-agnostic code, direct canvas control, maximum performance, or when you need the smallest bundle size.
• @lottiefiles/dotlottie-react: Use for React applications where you want a declarative component API and React lifecycle integration.

# Web (vanilla JS, Vue, Svelte, etc.)
npm install @lottiefiles/dotlottie-web

# React
npm install @lottiefiles/dotlottie-react

Install the Web Component package for rendering Lottie and DotLottie animations using npm.

npm install @lottiefiles/dotlottie-wc

You can install dotLottie implementation guidelines as a skill or command for your AI coding assistant to improve its ability to write code using this library. This provides the assistant with context regarding package selection, state machines, theming, and performance best practices.

curl -fsSL https://raw.githubusercontent.com/LottieFiles/dotlottie-web/main/guidelines/install.sh | bash

The repository contains several runnable example applications in the examples/ directory.

To run them locally:

1. Install dependencies and build the project.
2. Navigate to the desired example folder.
3. Start the development server.

Example highlights:

• web: State machines, themes, segments, layout.
• web-node: Server-side rendering to a buffer.
• react: Renderer selection (canvas/webgl/webgpu).
• vue: Theme toggling, ref/event patterns.
• solid: Signal-based state, theme/animation switching.
• wc: Web Component usage and event delegation.
• next: SSR-safe rendering with the App Router.

pnpm install && pnpm run build
cd examples/web
pnpm run dev

Install the Vue library for rendering Lottie and dotLottie animations using npm:

npm install @lottiefiles/dotlottie-vue