@lottiefiles/dotlottie-web
Advanced tools
A JavaScript library for rendering lottie and dotLottie animations in the browser.
dotLottie is an open-source file format that aggregates one or more Lottie files and their associated resources into a single file. They are ZIP archives compressed with the Deflate compression method and carry the file extension of ".lottie".
npm install @lottiefiles/dotlottie-web
After installation, you can import DotLottie in your JavaScript or TypeScript module:
<!-- Canvas element where the animation will be rendered -->
<canvas id="dotlottie-canvas" style="width: 300px; height:300px;"></canvas>
import { DotLottie } from '@lottiefiles/dotlottie-web';
const dotLottie = new DotLottie({
autoplay: true,
loop: true,
canvas: document.querySelector('#dotlottie-canvas'),
src: "https://lottie.host/4db68bbd-31f6-4cd8-84eb-189de081159a/IGmMCqhzpt.lottie", // or .json file
});
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta
name="viewport"
content="width=device-width, initial-scale=1, shrink-to-fit=no"
/>
<title>@lottiefiles/dotlottie-web | basic example</title>
</head>
<body>
<!-- Canvas element where the Lottie animation will be rendered -->
<canvas id="canvas" width="300" height="300"></canvas>
<script type="module">
import { DotLottie } from "https://cdn.jsdelivr.net/npm/@lottiefiles/dotlottie-web/+esm";
new DotLottie({
autoplay: true,
loop: true,
canvas: document.getElementById("canvas"),
src: "https://lottie.host/4db68bbd-31f6-4cd8-84eb-189de081159a/IGmMCqhzpt.lottie", // or .json file
});
</script>
</body>
</html>
The DotLottie constructor accepts a config object with the following properties:
| Property name | Type | Required | Default | Description |
|---|---|---|---|---|
autoplay | boolean | false | Auto-starts the animation on load. | |
loop | boolean | false | Determines if the animation should loop. | |
canvas | HTMLCanvasElement | OffscreenCanvas | ✔️ | undefined | Canvas element for animation rendering. |
src | string | undefined | URL to the animation data (.json or .lottie). | |
speed | number | 1 | Animation playback speed. 1 is regular speed. | |
data | string | ArrayBuffer | undefined | Animation data provided either as a Lottie JSON string or as an ArrayBuffer for .lottie animations. | |
mode | string | "forward" | Animation play mode. Accepts "forward", "reverse", "bounce", "reverse-bounce". | |
backgroundColor | string | undefined | Background color of the canvas. Accepts 6-digit or 8-digit hex color string (e.g., "#000000", "#000000FF"), | |
segment | [number, number] | [0, totalFrames - 1] | Animation segment. Accepts an array of two numbers, where the first number is the start frame and the second number is the end frame. | |
renderConfig | RenderConfig | {} | Configuration for rendering the animation. | |
useFrameInterpolation | boolean | true | Determines if the animation should update on subframes. If set to false, the original AE frame rate will be maintained. If set to true, it will refresh at each requestAnimationFrame, including intermediate values. The default setting is true. | |
marker | string | undefined | The lottie named marker to play. | |
layout | Layout | undefined | The animation layout configuration. |
The layout object accepts the following properties:
| Property name | Type | Required | Default | Description |
|---|---|---|---|---|
fit | string | "contain" | The fit mode of the animation. Accepts "contain", "cover", "fill", "fit-width", "fit-height" and "none". | |
align | [number, number] | [0.5, 0.5] | The alignment of the animation in the canvas. Origin is at the top-left corner where [0, 0] is the top-left corner and [1, 1] is the bottom-right corner. |
The renderConfig object accepts the following properties:
| Property name | Type | Required | Default | Description |
|---|---|---|---|---|
devicePixelRatio | number | window.devicePixelRatio | 1 | The device pixel ratio. |
DotLottie instances expose the following properties:
| Property | Type | Description |
|---|---|---|
currentFrame | number | Represents the animation's currently displayed frame number. |
duration | number | Specifies the animation's total playback time in milliseconds. |
totalFrames | number | Denotes the total count of individual frames within the animation. |
loop | boolean | Indicates if the animation is set to play in a continuous loop. |
speed | number | Represents the playback speed factor; e.g., 2 would mean double speed. |
loopCount | number | Tracks how many times the animation has completed its loop. |
direction | string | Reflects the current playback direction; e.g., 1 would mean forward, -1 would mean reverse. |
mode | string | Reflects the current playback mode. |
isPaused | boolean | Reflects whether the animation is paused or not. |
isStopped | boolean | Reflects whether the animation is stopped or not. |
isPlaying | boolean | Reflects whether the animation is playing or not. |
segment | [number, number] | Reflects the frames range of the animations. where segment[0] is the start frame and segment[1] is the end frame. |
backgroundColor | string | Gets the background color of the canvas. |
autoplay | boolean | Indicates if the animation is set to auto-play. |
isFrozen | boolean | Reflects whether the animation loop is stopped or not. |
isLoaded | boolean | Reflects whether the animation is loaded or not. |
useFrameInterpolation | boolean | Reflects whether the animation should update on subframes. |
renderConfig | RenderConfig | Configuration for rendering the animation. |
manifest | Manifest | null | The manifest of the loaded dotLottie file. |
marker | string | The lottie named marker to play. |
layout | Layout | The animation layout configuration. |
activeThemeId | string | The loaded theme id from the .lottie file. |
activeAnimationId | string | The loaded animation id from the .lottie file. |
segmentDuration | number | The duration of the current segment, if no segment is set, it will return the duration of the whole animation. |
canvas | HTMLCanvasElement | OffscreenCanvas | The canvas element for animation rendering. |
This object contains the manifest of the loaded dotLottie file. as described in the dotLottie structure.
DotLottie instances expose the following methods that can be used to control the animation:
| 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. |
setFrame(frame: number) | Directly navigates the animation to a specified frame. |
addEventListener(event: string, listener: Function) | Registers a function to respond to a specific animation event. |
removeEventListener(event: string, listener?: Function) | Removes a previously registered function from responding to a specific animation event. |
destroy() | Destroys the renderer instance and unregisters all event listeners. This method should be called when the canvas is removed from the DOM to prevent memory leaks. |
load(config: Config) | Loads a new configuration or a new animation. |
setMode(mode: string) | Sets the animation play mode. |
setSegment(startFrame: number, endFrame: number) | Sets the start and end frame of the animation. |
freeze() | Freezes the animation by stopping the animation loop. |
unfreeze() | Unfreezes the animation by resuming the animation loop. |
setBackgroundColor(color: string) | Sets the background color of the canvas. |
resize() | This method adjusts the canvas size to match its bounding box dimensions, considering the device's pixel ratio. This prevents the canvas from appearing blurry on high-resolution screens. Call this method when the window or the canvas element is resized. |
setUseFrameInterpolation(useFrameInterpolation: boolean) | Sets whether the animation should update on subframes. |
setRenderConfig(renderConfig: RenderConfig) | Sets the render configuration. check RenderConfig for more details. |
loadAnimation(animationId: string) | Loads a new animation from the .lottie file, using its ID as specified in the manifest.json file of the .lottie file. |
setMarker(marker: string) | Sets the lottie named marker to play. |
setLayout(layout: Layout) | Sets the animation layout configuration. |
loadTheme(themeId: string) | Loads a new theme from the .lottie file, using its ID as specified in the manifest.json file of the .lottie file. |
loadThemeData(themeData: string) | Loads a new theme from the provided theme data. |
setViewport(x: number, y: number, width: number, height: number) | Sets the viewport of the animation, where x and y are the top-left corner of the viewport, and width and height are the dimensions of the viewport, this will crop the animation to the specified viewport. |
loadStateMachineData(stateMachineData: string) | Loads the state machine data as a json string. |
animationSize(): {width: number, height: number} | Retrieves the original lottie animation size. |
setStateMachineBooleanContext(name: string, value: boolean) | Sets the state machine context with a boolean value. |
setStateMachineStringContext(name: string, value: string) | Sets the state machine context with a string value. |
setStateMachineNumericContext(name: string, value: number) | Sets the state machine context with a numeric value. |
The DotLottie class exposes the following static methods:
| Method | Description |
|---|---|
setWasmUrl(url: string) | Sets the URL to the renderer.wasm binary. |
The DotLottie instance emits the following events that can be listened to via the addEventListener method:
| Event | Description | Event Parameter (Type and Fields) |
|---|---|---|
load | Emitted when the animation is loaded. | LoadEvent { type: 'load' } |
loadError | Emitted when there's an error loading the animation. | LoadErrorEvent { type: 'loadError', error: Error } |
play | Emitted when the animation starts playing. | PlayEvent { type: 'play' } |
pause | Emitted when the animation is paused. | PauseEvent { type: 'pause' } |
stop | Emitted when the animation is stopped. | StopEvent { type: 'stop' } |
loop | Emitted when the animation completes a loop. | LoopEvent { type: 'loop', loopCount: number } |
complete | Emitted when the animation completes. | CompleteEvent { type: 'complete' } |
frame | Emitted when the animation reaches a new frame. | FrameEvent { type: 'frame', currentFrame: number } |
destroy | Emitted when the animation is destroyed. | DestroyEvent { type: 'destroy' } |
freeze | Emitted when the animation is freezed and the animation loop stops. | FreezeEvent { type: 'freeze' } |
unfreeze | Emitted when the animation is unfreezed and the animation loop resumes. | UnfreezeEvent { type: 'unfreeze' } |
render | Emitted when a new frame is rendered to the canvas. | RenderEvent { type: 'render', currentFrame: number } |
pnpm install
pnpm dev
pnpm build
pnpm test
FAQs
Lottie and DotLottie player for the web
The npm package @lottiefiles/dotlottie-web receives a total of 98,047 weekly downloads. As such, @lottiefiles/dotlottie-web popularity was classified as popular.
We found that @lottiefiles/dotlottie-web demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.