@lottiefiles/dotlottie-web
Advanced tools
🚧 Beta Alert: We're still refining! The APIs in this package may undergo changes.
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="my-canvas" width="300px" height="300px"></canvas>
import { DotLottie } from '@lottiefiles/dotlottie-web';
const dotLottie = new DotLottie({
autoplay: true,
loop: true,
canvas: document.getElementById('my-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://unpkg.com/@lottiefiles/dotlottie-web@latest/dist/index.js";
new DotLottie({
autoplay: true,
loop: true,
canvas: document.getElementById("canvas"),
src:
"https://lottie.host/5f7f4690-6311-4279-82e4-38c2eab146ab/niPwIBUnGa.json"
});
</script>
</body>
</html>
DotLottie offers an automatic canvas resizing behavior to ensure optimal animation quality, especially when the canvas size changes dynamically, such as during browser window resizing or layout adjustments. This behavior is particularly useful when the canvas does not have fixed width and height attributes set, as it maintains the quality of the animation by adjusting the canvas's internal drawing buffer to match its display size.
For this behavior to work correctly, the canvas element must be styled using CSS to take up 100% of the width of its parent container. Additionally, you can use the aspect-ratio property to maintain a specific aspect ratio for the canvas. Adjust this property as needed for your design requirements. For example:
<canvas id="canvas" style="width: 100%; aspect-ratio: 1"></canvas>
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 | ✔️ | 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 | "normal" | Animation play mode. Accepts "normal", "reverse", "bounce", "bounce-reverse". | |
backgroundColor | string | undefined | Background color of the canvas. e.g., "#000000", "rgba(0, 0, 0, 0.5)" or "transparent". |
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. |
playing | boolean | Reflects whether the animation is in active playback or not |
direction | string | Reflects the current playback direction; e.g., 1 would mean forward, -1 would mean reverse. |
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. |
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 |
|---|---|
load | Emitted when the animation is loaded. |
loadError | Emitted when there's an error loading the animation. |
play | Emitted when the animation starts playing. |
pause | Emitted when the animation is paused. |
stop | Emitted when the animation is stopped. |
loop | Emitted when the animation completes a loop. |
complete | Emitted when the animation completes. |
frame | Emitted when the animation reaches a new frame. |
pnpm install
pnpm dev
pnpm build
Note: This step is necessary only if you wish to update the src/renderer.cpp file or the thorvg version being used. If not, you can skip this step.
Using Docker (Recommended):
pnpm build:wasm:docker
Using Emscripten SDK:
Ensure Emscripten SDK is installed.
pnpm build:wasm /path/to/emsdk/
FAQs
Lottie and DotLottie player for the web
The npm package @lottiefiles/dotlottie-web receives a total of 183,588 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 0 open source maintainers 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.
Research
Security News
The Socket Research Team has discovered six new malicious npm packages linked to North Korea’s Lazarus Group, designed to steal credentials and deploy backdoors.
Security News
Socket CEO Feross Aboukhadijeh discusses the open web, open source security, and how Socket tackles software supply chain attacks on The Pair Program podcast.
Security News
Opengrep continues building momentum with the alpha release of its Playground tool, demonstrating the project's rapid evolution just two months after its initial launch.