dotLottie Web Player API Reference

Configuration

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

Property	Type	Required	Default	Description
`canvas`	HTMLCanvasElement	✔️	`undefined`	Canvas element for animation rendering
`src`	string		`undefined`	URL to the animation data (`.json` or `.lottie`)
`data`	string \| ArrayBuffer \| Record<string, unknown>		`undefined`	Animation data as a Lottie JSON string, an ArrayBuffer for .lottie files, or a pre-parsed JSON object
`autoplay`	boolean		`false`	Auto-starts the animation on load
`loop`	boolean		`false`	Determines if the animation should loop
`loopCount`	number		`0`	Number of additional loop repetitions (0 = infinite when `loop` is true)
`speed`	number		`1`	Animation playback speed. 1 is regular speed
`mode`	string		`"forward"`	Animation play mode. Accepts `"forward"`, `"reverse"`, `"bounce"`, `"reverse-bounce"`
`segment`	[number, number]		`[0, totalFrames - 1]`	Animation segment. Accepts an array of two numbers: start frame and end frame
`marker`	string		`undefined`	The lottie named marker to play
`animationId`	string		`undefined`	ID of the animation to load from a multi-animation dotLottie file
`themeId`	string		`undefined`	The ID of the dotLottie theme to initially use
`backgroundColor`	string		`undefined`	Background color of the canvas. Accepts 6-digit or 8-digit hex color string (e.g., `"#000000"`, `"#000000FF"`)
`layout`	Layout		`undefined`	The animation layout configuration
`renderConfig`	RenderConfig		`{}`	Configuration for rendering the animation (see Render Configuration)
`useFrameInterpolation`	boolean		`true`	Determines if the animation should update on subframes. Set `false` for potentially better performance if subframe accuracy isn't needed.
`stateMachineId`	string		`undefined`	ID of the state machine to load on animation load
`stateMachineConfig`	StateMachineConfig		`undefined`	Security configuration for the state machine (see StateMachineConfig)

Properties

DotLottie instances expose the following read-only properties:

Property	Type	Description
`currentFrame`	number	The animation's currently displayed frame number
`duration`	number	The animation's total playback time in milliseconds
`segmentDuration`	number	Duration of the current segment in milliseconds
`totalFrames`	number	Total count of individual frames within the animation
`loop`	boolean	Whether the animation is set to play in a continuous loop
`speed`	number	Playback speed factor (e.g., 2 means double speed)
`loopCount`	number	Number of times the animation has completed its loop
`mode`	string	Current playback mode
`isPaused`	boolean	Whether the animation is paused
`isStopped`	boolean	Whether the animation is stopped
`isPlaying`	boolean	Whether the animation is playing
`isLoaded`	boolean	Whether the animation is loaded
`isReady`	boolean	Whether the WASM renderer module is initialized
`isFrozen`	boolean	Whether the animation loop is frozen
`isStateMachineRunning`	boolean	Whether a state machine is currently running
`segment`	[number, number]	Current frame range being played
`backgroundColor`	string	Current background color of the canvas
`autoplay`	boolean	Whether the animation is set to auto-play
`useFrameInterpolation`	boolean	Whether the animation updates on subframes
`renderConfig`	RenderConfig	Current rendering configuration
`manifest`	Manifest \| null	The manifest of the loaded dotLottie file
`marker`	string \| undefined	The current lottie named marker
`layout`	Layout \| undefined	The current animation layout configuration
`activeThemeId`	string	The ID of the currently active theme
`activeAnimationId`	string	The ID of the currently active animation
`canvas`	HTMLCanvasElement \| OffscreenCanvas \| RenderSurface \| null	The canvas element used for rendering
`buffer`	Uint8Array \| null	The raw pixel buffer for the current frame

Methods

Playback Control

Method	Description
`play()`	Begins playback from the current animation position
`pause()`	Pauses the animation without resetting its position
`stop()`	Halts playback and returns the animation to its initial frame
`setSpeed(speed: number)`	Sets the playback speed with the given multiplier
`setLoop(loop: boolean)`	Configures whether the animation should loop continuously
`setLoopCount(loopCount: number)`	Sets the number of loop repetitions
`setFrame(frame: number)`	Directly navigates the animation to a specified frame
`setMode(mode: string)`	Sets the animation play mode (`"forward"`, `"reverse"`, `"bounce"`, `"reverse-bounce"`)
`setSegment(startFrame: number, endFrame: number)`	Sets the start and end frame of the animation
`setMarker(marker: string)`	Sets the lottie named marker to play
`freeze()`	Freezes the animation by stopping the animation loop
`unfreeze()`	Unfreezes the animation by resuming the animation loop
`setUseFrameInterpolation(useFrameInterpolation: boolean)`	Sets whether the animation should update on subframes. Setting `false` may improve performance.
`tween(frame: number, duration: number)`	Smoothly tweens the animation from the current frame to the specified frame over the given duration (ms)
`tweenToMarker(marker: string, duration: number)`	Smoothly tweens the animation to the start of the named marker over the given duration (ms)
`markers()`	Returns all markers defined in the animation as an array of `Marker` objects

Animation Loading & Themes

Method	Description
`load(config: Config)`	Loads a new configuration or animation
`loadAnimation(animationId: string)`	Loads a specific animation from a multi-animation `.lottie` file by ID
`setTheme(themeId: string)`	Loads a theme by ID from the `.lottie` file
`setThemeData(themeData: string)`	Loads a theme from the provided theme data string
`resetTheme()`	Resets to the default theme

Slot System (Dynamic Properties)

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

Method	Description
`getSlotIds()`	Returns an array of all available slot IDs
`getSlotType(slotId: string)`	Returns the type of the slot (`"color"`, `"scalar"`, `"vector"`, `"gradient"`, `"text"`, `"image"`)
`getSlot(slotId: string)`	Returns the current value of a slot
`getSlots()`	Returns all slot values as a record
`setSlots(slots: Record<string, unknown>)`	Sets multiple slot values at once
`setColorSlot(slotId: string, value: ColorSlotValue)`	Sets a color slot value (static or animated)
`setScalarSlot(slotId: string, value: ScalarSlotValue)`	Sets a scalar (numeric) slot value
`setVectorSlot(slotId: string, value: VectorSlotValue)`	Sets a vector slot value
`setGradientSlot(slotId: string, value: GradientSlotValue, colorStopCount: number)`	Sets a gradient slot value
`setTextSlot(slotId: string, value: TextSlotValue)`	Sets a text slot value
`resetSlot(slotId: string)`	Resets a slot to its default value
`clearSlot(slotId: string)`	Clears a slot value
`resetSlots()`	Resets all slots to their default values
`clearSlots()`	Clears all slot values

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

Method	Description
`setBackgroundColor(color: string)`	Sets the background color of the canvas
`setLayout(layout: Layout)`	Sets the animation layout configuration
`setRenderConfig(renderConfig: RenderConfig)`	Sets the render configuration
`setViewport(x: number, y: number, width: number, height: number)`	Sets a custom viewport within the canvas
`setTransform(transform: Transform)`	Applies a 3×3 affine transformation matrix to the animation
`getTransform()`	Returns the current transformation matrix
`setCanvas(canvas: HTMLCanvasElement \| OffscreenCanvas)`	Reassigns the player to a different canvas element
`resize()`	Adjusts the canvas size to match its bounding box dimensions
`animationSize()`	Returns the intrinsic `{ width, height }` of the animation
`getLayerBoundingBox(layerName: string)`	Returns the bounding box `[x, y, width, height]` of a named layer

State Machine

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

Method	Description
`stateMachineLoad(stateMachineId: string)`	Loads a state machine by ID
`stateMachineLoadData(stateMachineData: string)`	Loads a state machine from a JSON string
`stateMachineSetConfig(config: StateMachineConfig \| null)`	Configures security settings for the state machine
`stateMachineStart()`	Starts the loaded state machine
`stateMachineStop()`	Stops the state machine
`stateMachineGetStatus()`	Returns the state machine status string
`stateMachineGetCurrentState()`	Returns the name of the active state
`stateMachineGetActiveId()`	Returns the ID of the active state machine
`stateMachineGet(stateMachineId: string)`	Returns the state machine definition JSON
`stateMachineGetListeners()`	Returns names of all active listeners
`stateMachineOverrideState(state: string, immediate: boolean)`	Overrides the current state
`stateMachineFireEvent(name: string)`	Fires a named custom event
`stateMachinePostClickEvent(x: number, y: number)`	Posts a click event at canvas coordinates
`stateMachinePostPointerUpEvent(x: number, y: number)`	Posts a pointer-up event at canvas coordinates
`stateMachinePostPointerDownEvent(x: number, y: number)`	Posts a pointer-down event at canvas coordinates
`stateMachinePostPointerMoveEvent(x: number, y: number)`	Posts a pointer-move event at canvas coordinates
`stateMachinePostPointerEnterEvent(x: number, y: number)`	Posts a pointer-enter event at canvas coordinates
`stateMachinePostPointerExitEvent(x: number, y: number)`	Posts a pointer-exit event at canvas coordinates
`stateMachineSetBooleanInput(name: string, value: boolean)`	Sets a boolean input
`stateMachineSetNumericInput(name: string, value: number)`	Sets a numeric input
`stateMachineSetStringInput(name: string, value: string)`	Sets a string input
`stateMachineGetBooleanInput(name: string)`	Gets a boolean input value
`stateMachineGetNumericInput(name: string)`	Gets a numeric input value
`stateMachineGetStringInput(name: string)`	Gets a string input value
`stateMachineGetInputs()`	Returns the names of all defined inputs

Event Listeners

Method	Description
`addEventListener(event: string, listener: Function)`	Registers a function to respond to a specific animation event
`removeEventListener(event: string, listener?: Function)`	Removes a previously registered event listener

Lifecycle

Method	Description
`destroy()`	Destroys the renderer instance and unregisters all event listeners. Crucial for cleanup to prevent memory leaks when done with an animation.

Static Methods

Method	Description
`DotLottie.setWasmUrl(url: string)`	Sets the URL to the renderer.wasm binary
`DotLottie.registerFont(fontName: string, fontSource: string \| ArrayBuffer \| Uint8Array)`	Registers a custom font for use in text slots
`DotLottie.transformThemeToLottieSlots(theme: string, slots: string)`	Utility to transform theme data to Lottie slot format

GPU-Accelerated Rendering

DotLottieWebGL

The DotLottieWebGL class provides WebGL2-accelerated rendering. It shares the same API as DotLottie but uses a WebGLConfig constructor that requires an HTMLCanvasElement.

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

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

Static Method	Description
`DotLottieWebGL.setWasmUrl(url: string)`	Sets the URL to the WebGL renderer WASM binary

WebGL2 must be supported by the browser. All instance methods, properties, and events from DotLottie are available on DotLottieWebGL.

DotLottieWebGPU

The DotLottieWebGPU class provides WebGPU-accelerated rendering for the highest performance.

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

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

The WebGPUConfig extends the standard Config with:

Property	Type	Required	Default	Description
`device`	`GPUDevice`	No	`undefined`	An existing WebGPU device. If omitted, one is requested automatically.

Static Method	Description
`DotLottieWebGPU.setWasmUrl(url: string)`	Sets the URL to the WebGPU renderer WASM binary

:::warning WebGPU is an emerging API with limited browser support. Check browser compatibility before using in production. :::

Events

The following events can be listened to via addEventListener:

Animation Events

Event	Description	Event Parameter
`ready`	WASM renderer is initialized	`{ type: 'ready' }`
`load`	Animation is loaded	`{ type: 'load' }`
`loadError`	Error loading animation	`{ type: 'loadError', error: Error }`
`play`	Animation starts playing	`{ type: 'play' }`
`pause`	Animation is paused	`{ type: 'pause' }`
`stop`	Animation is stopped	`{ type: 'stop' }`
`loop`	Animation completes a loop	`{ type: 'loop', loopCount: number }`
`complete`	Animation completes	`{ type: 'complete' }`
`frame`	Animation reaches new frame	`{ type: 'frame', currentFrame: number }`
`render`	New frame is rendered	`{ type: 'render', currentFrame: number }`
`freeze`	Animation is frozen	`{ type: 'freeze' }`
`unfreeze`	Animation is unfrozen	`{ type: 'unfreeze' }`
`destroy`	Animation is destroyed	`{ type: 'destroy' }`
`renderError`	Rendering error occurred	`{ type: 'renderError', error: Error }`

State Machine Events

Event	Description	Event Parameter
`stateMachineStart`	State machine started	`{ type: 'stateMachineStart' }`
`stateMachineStop`	State machine stopped	`{ type: 'stateMachineStop' }`
`stateMachineTransition`	State transition occurred	`{ type: 'stateMachineTransition', fromState: string, toState: string }`
`stateMachineStateEntered`	Entered a new state	`{ type: 'stateMachineStateEntered', state: string }`
`stateMachineStateExit`	Exited a state	`{ type: 'stateMachineStateExit', state: string }`
`stateMachineCustomEvent`	Custom event emitted by state machine	`{ type: 'stateMachineCustomEvent', eventName: string }`
`stateMachineError`	State machine error	`{ type: 'stateMachineError', error: string }`
`stateMachineBooleanInputValueChange`	Boolean input value changed	`{ type, inputName: string, oldValue: boolean, newValue: boolean }`
`stateMachineNumericInputValueChange`	Numeric input value changed	`{ type, inputName: string, oldValue: number, newValue: number }`
`stateMachineStringInputValueChange`	String input value changed	`{ type, inputName: string, oldValue: string, newValue: string }`
`stateMachineInputFired`	An input fired	`{ type: 'stateMachineInputFired', inputName: string }`
`stateMachineInternalMessage`	Internal state machine message	`{ type: 'stateMachineInternalMessage', message: string }`

Layout Configuration

The layout object accepts the following properties:

Property	Type	Required	Default	Description
`fit`	string		`"contain"`	The fit mode of the animation. Accepts `"contain"`, `"cover"`, `"fill"`, `"fit-width"`, `"fit-height"`, `"none"`
`align`	[number, number]		`[0.5, 0.5]`	The alignment of the animation in the canvas. `[0, 0]` is top-left and `[1, 1]` is bottom-right

Render Configuration

The renderConfig object allows customization of rendering settings:

Property	Type	Required	Default	Description
`devicePixelRatio`	number	No	`window.devicePixelRatio * 0.75` if DPI > 1, else `1`	Controls the pixel ratio for rendering
`freezeOnOffscreen`	boolean	No	`true`	Freezes animation when offscreen to conserve resources (improves performance when many animations are present but not visible)
`autoResize`	boolean	No	`false`	Automatically adjusts animation size when canvas element is resized
`quality`	number	No	`undefined`	Rendering quality level (0–100). Controls the resolution scale of the internal render surface. A value of 100 renders at full resolution. Lower values reduce the resolution proportionally, improving performance at the cost of visual fidelity. Useful for complex animations where performance is prioritised.

StateMachineConfig

The stateMachineConfig object controls security settings for state machine execution:

Property	Type	Description
`openUrlPolicy`	object	Controls URL-opening behavior triggered by state machines
`openUrlPolicy.requireUserInteraction`	boolean	When `true`, URLs can only be opened in response to direct user interaction
`openUrlPolicy.whitelist`	string[]	List of allowed URL prefixes that the state machine may open

Type Definitions

Slot Types

Type	Definition	Description
`ColorSlotValue`	`Color \| Array<Keyframe<Color>>`	Static or animated color
`ScalarSlotValue`	`number \| Array<Keyframe<number>>`	Static or animated scalar (number)
`VectorSlotValue`	`Vector \| Array<Keyframe<Vector>>`	Static or animated vector `[x, y]`
`GradientSlotValue`	`Gradient \| Array<Keyframe<Gradient>>`	Static or animated gradient with color stops
`TextSlotValue`	`TextDocument`	Static text with optional font, size, color
`SlotType`	`"color" \| "gradient" \| "image" \| "text" \| "scalar" \| "vector"`	Possible 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 you might access include:

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.

For a detailed explanation of the manifest structure and all its properties, please refer to the dotLottie Format Structure documentation.