dotLottie Web Player API Reference

Configuration

The DotLottie constructor accepts a configuration object with the following properties:

Properties

DotLottie instances expose the following read-only properties:

Methods

Playback Control

Animation Loading & Themes

Slot System (Dynamic Properties)

Slots allow runtime modification of animation properties such as colors, text, and gradients.

Methods that modify state (setTheme, resetTheme, setThemeData, setTransform, setViewport, tween, tweenToMarker, stateMachineLoad, stateMachineStart, stateMachineOverrideState, and all slot setters like setColorSlot, resetSlot, clearSlot, etc.) return boolean — true on success, false on failure.

Rendering & Layout

State Machine

See the State Machines guide for full documentation. Quick reference:

Event Listeners

Lifecycle

Static Methods

DotLottie.preload() starts the WASM download (~500 KB compressed) before any player is constructed. A player constructed afterwards uses the in-progress download instead of starting its own:

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

// At app or route load, before any player is constructed:
DotLottie.preload();

When a custom WASM binary is used, setWasmUrl() must be called before preload():

DotLottie.setWasmUrl("/assets/dotlottie-player.wasm");
DotLottie.preload();

GPU-Accelerated Rendering

The WebGL2 and WebGPU backends live on package subpaths, and each one exports its player class as DotLottie. Alias it on import to name the backend and to avoid a collision when a file uses more than one. For guidance on choosing a backend, detecting support, and falling back, see Render on the GPU with WebGL or WebGPU.

Both classes narrow the constructor config: canvas is required and must be an HTMLCanvasElement, so OffscreenCanvas and RenderSurface are not accepted. Neither backend has a Web Worker equivalent — DotLottieWorker is exported only from the package root and always renders on the CPU.

WebGL renderer

Import from @lottiefiles/dotlottie-web/webgl for WebGL2-accelerated rendering, configured with a WebGLConfig:

import { DotLottie as DotLottieWebGL } from "@lottiefiles/dotlottie-web/webgl";

const animation = new DotLottieWebGL({
  canvas: document.getElementById("my-canvas") as HTMLCanvasElement,
  src: "animation.lottie",
  autoplay: true,
});

Both static methods apply only to the WebGL backend's own WASM loader; calling them on DotLottie has no effect here. The browser must support WebGL2. All instance methods, properties, and events from DotLottie are available.

WebGPU renderer

Import from @lottiefiles/dotlottie-web/webgpu for WebGPU-accelerated rendering, configured with a WebGPUConfig:

import { DotLottie as DotLottieWebGPU } from "@lottiefiles/dotlottie-web/webgpu";

const animation = new DotLottieWebGPU({
  canvas: document.getElementById("my-canvas") as HTMLCanvasElement,
  src: "animation.lottie",
  autoplay: true,
  device: gpuDevice, // optional: pass your own GPUDevice
});

The WebGPUConfig extends the standard Config with:

The instance also exposes the device it renders with:

When you omit device, the player requests an adapter and device during initialization and destroys that device in destroy(). A device you supply is left untouched.

:::warning WebGPU is an emerging API with limited browser support. Initialization failures on either GPU backend — a missing navigator.gpu or no available adapter for WebGPU, no WebGL2 context for WebGL — do not throw from the constructor; they surface as a loadError event. :::

Events

The following events can be listened to via addEventListener:

Animation Events

State Machine Events

Layout Configuration

The layout object accepts the following properties:

Render Configuration

The renderConfig object allows customization of rendering settings:

StateMachineConfig

The stateMachineConfig object controls security settings for state machine execution:

Type Definitions

AssetResolver

AssetResolver is a synchronous callback used to supply bytes for assets that an animation references but does not embed — for example, images stored outside the .lottie container.

type AssetResolver = (src: string) => ArrayBuffer | Uint8Array | null | undefined;

The resolver is called synchronously while the animation loads, so the asset bytes must already be available in memory. Return null or undefined to leave an asset unresolved — unresolved images render as a gray placeholder.

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

// Pre-load your assets into a Map (or any lookup you choose)
const assets = new Map<string, Uint8Array>();
assets.set("/images/logo.png", await fetchAsBytes("/images/logo.png"));

const dotLottie = new DotLottie({
  canvas: document.querySelector("#canvas") as HTMLCanvasElement,
  src: "animation.json",
  autoplay: true,
  assetResolver: (src) => assets.get(src) ?? null,
});

:::warning assetResolver is not supported by DotLottieWorker. Functions cannot be transferred across the worker boundary — if you pass assetResolver to DotLottieWorker, it will be silently dropped and a console warning will be logged. Use DotLottie instead when your animation references external assets. :::

If you call load() to reload the animation with a new configuration, pass assetResolver again in the new config — load() replaces the full configuration.

Slot Types

Transform

A Transform is a 9-element array [a, b, c, d, e, f, g, h, i] representing a 3×3 affine transformation matrix applied to the entire animation on the canvas.

Marker

interface Marker {
  name: string;
  time: number;
  duration: number;
}

Data

The Data type represents animation data that can be passed to the data configuration option:

type Data = string | ArrayBuffer | Record<string, unknown>;

• string — A Lottie JSON string

• ArrayBuffer — A .lottie file binary

• Record<string, unknown> — A pre-parsed Lottie JSON object

Manifest Object

The manifest property returns the parsed manifest.json object from the loaded .lottie file (or null if a .json file was loaded or loading failed). This object contains metadata about the animation(s), themes, and state machines within the dotLottie file.

Key properties:

• manifest.animations: An array of objects, each describing an animation within the file (containing id, loop, speed, etc.).

• manifest.themes: An array describing available themes.

• manifest.stateMachines: An array describing available state machines.

• manifest.version: The dotLottie format version string.

• manifest.generator: The tool that generated the file.

The dotLottie Format Structure documentation describes the manifest structure and all its properties.

Related

• Render your first animation — tutorial

• Load animations, Control playback, and the other how-to guides

• How the web player works — the rendering model behind this API