dotLottie Web Quick Start

What is dotLottie Web?

dotLottie Web 是 LottieFiles 官方提供的 Web 动画渲染库，用于在浏览器和 Node.js 环境中播放 .lottie 和 Lottie (.json) 动画文件。它基于 Canvas 和 WebAssembly 构建，提供高性能的动画渲染能力，并支持 React、Vue、Svelte、Solid 等主流前端框架的封装组件。

dotLottie 格式是基于 ZIP 压缩的动画文件格式，相比传统 Lottie JSON 文件体积更小，支持多动画打包、素材内嵌、状态机和主题插槽等高级特性。

Core Features

• High-Performance Rendering — Canvas 2D + WebAssembly, supports Web Worker off-screen rendering
• Multi-Framework Support — Official wrappers for React, Vue, Svelte, Solid, and Web Components
• .lottie Format — Open format with ZIP compression, multi-animation, state machines, and theming
• State Machine Interactivity — Built-in state machine for click, hover interactions without code changes
• Theme Slots — Runtime dynamic modification of animation colors, scalars, vectors, and more
• Auto Optimization — Automatic freeze when offscreen + 75% DPR for better performance
• Isomorphic — Works in both browser and Node.js 18+ environments

Installation

# Core (vanilla JS / Vue / Svelte)
npm install @lottiefiles/dotlottie-web

# React
npm install @lottiefiles/dotlottie-react

# Vue
npm install @lottiefiles/dotlottie-vue

# Svelte
npm install @lottiefiles/dotlottie-svelte

# Solid
npm install @lottiefiles/dotlottie-solid

# Web Component
npm install @lottiefiles/dotlottie-wc

Requirements: Node.js 18+, modern browser with WebAssembly support (Chrome 57+, Firefox 52+, Safari 11+, Edge 16+).

Your First Animation

Vanilla JavaScript:

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

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

React:

import { DotLottieReact } from '@lottiefiles/dotlottie-react';

function Animation() {
  return (
    <DotLottieReact
      src="https://example.com/animation.lottie"
      autoplay
      loop
    />
  );
}

Key takeaway: .lottie format is preferred over .json — smaller file size, supports multiple animations, embedded assets, state machines, and theming.

Common Patterns

Web Worker for Performance

Offload rendering to a Web Worker to keep the main thread free:

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

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

Use DotLottieWorker when you have multiple animations, complex animations with many layers, or heavy JS operations running alongside.

Playback Control

// Play / Pause
dotLottie.play();
dotLottie.pause();

// Jump to specific frame
dotLottie.setFrame(60);

// Play segment
dotLottie.setSegment(0, 60);
dotLottie.play();

// Play by marker
dotLottie.setMarker('intro');
dotLottie.play();

// Set speed
dotLottie.setSpeed(2); // 2x speed

Event Handling

dotLottie.addEventListener('load', () => {
  console.log('Animation loaded');
});

dotLottie.addEventListener('play', () => {
  console.log('Playing');
});

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

dotLottie.addEventListener('frame', ({ currentFrame }) => {
  console.log('Frame:', currentFrame);
});

// Clean up
dotLottie.removeEventListener('load', handler);

Advanced Topics

State Machine Interactivity

.lottie files can embed state machines for interactive animations:

const dotLottie = new DotLottie({
  canvas,
  src: 'interactive.lottie', // Contains state machine
  autoplay: true,
});

// Fire state transition events
dotLottie.stateMachineFireEvent('click');
dotLottie.stateMachineFireEvent('hover');
dotLottie.stateMachineFireEvent('custom-event');

// Set state inputs
dotLottie.stateMachineSetNumericInput('progress', 0.5);
dotLottie.stateMachineSetBooleanInput('isActive', true);
dotLottie.stateMachineSetStringInput('mode', 'dark');

Theme Slots

Runtime modification of animation colors and values:

// Use embedded theme
const dotLottie = new DotLottie({
  canvas,
  src: 'themed.lottie',
  themeId: 'dark-mode',
});

// Or apply theme data directly (dotLottie 2.0 spec)
dotLottie.setThemeData(JSON.stringify({
  rules: [
    { id: 'primary-color', value: [1, 0.34, 0.13] }, // RGB 0-1
  ]
}));

Dynamic Slots

// Get available slots
const slotIds = dotLottie.getSlotIds();
const slotType = dotLottie.getSlotType('slot-id');

// Set slot values
dotLottie.setColorSlot('slot-id', [1, 0, 0]); // RGB
dotLottie.setScalarSlot('slot-id', 2.5);
dotLottie.setVectorSlot('slot-id', [1, 2, 3]);

// Reset slots
dotLottie.resetSlot('slot-id');
dotLottie.clearSlots();

Multi-Animation Files

A single .lottie file can contain multiple animations:

// Load specific animation
dotLottie.loadAnimation('animation-2');

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

Best Practices

1. Prefer .lottie over .json — Smaller size, more features
2. Use Web Workers for complex animations — Keeps main thread responsive
3. Lazy load animations — Only load when visible using IntersectionObserver
4. Use dynamic import for SSR/Next.js — dotLottie requires browser APIs
5. Clean up resources — Call dotLottie.destroy() in vanilla JS when done
6. Adjust Device Pixel Ratio wisely — Default 75% is optimized, set higher for retina
7. Keep frame interpolation enabled — useFrameInterpolation: true (default) ensures smooth playback

FAQ

How to handle mobile performance issues?

Use DotLottieWorker to move rendering to a Web Worker and avoid blocking the main thread.

How to implement click interaction?

Use state machines (define click events in the animation file), or manually control:

canvas.addEventListener('click', () => {
  dotLottie.setFrame(0);
  dotLottie.setLoop(false);
  dotLottie.play();
});

How to control playback with scroll?

window.addEventListener('scroll', () => {
  const progress = window.scrollY / (document.body.scrollHeight - window.innerHeight);
  const frame = progress * dotLottie.totalFrames;
  dotLottie.setFrame(frame);
});

How to dynamically change animation colors?

Use theme slots or setColorSlot():

dotLottie.setColorSlot('my-slot-id', [1, 0.34, 0.13]); // RGB 0-1

Can I use it in Node.js?

Yes, Node.js 18+ is supported, but requires a canvas implementation.

How to debug animations?

console.log('Loaded:', dotLottie.isLoaded);
console.log('Duration:', dotLottie.duration);
console.log('Total Frames:', dotLottie.totalFrames);
console.log('Current Frame:', dotLottie.currentFrame);
console.log('Is Playing:', dotLottie.isPlaying);
console.log('Manifest:', dotLottie.manifest);

Next Steps

• Official Documentation — Full API reference
• dotLottie 2.0 Spec — File format specification
• dotLottie Viewer — Test and debug animations
• GitHub Repository — Source code and examples
• dotLottie Website — Create .lottie files
• LottieDocs — Original Lottie format docs