@lottiefiles/dotlottie-wc
v0.9.27
Published
Web component wrapper around the dotlottie-web library
Readme
@lottiefiles/dotlottie-wc
[!TIP] Looking for animations to use with this player? Browse 100,000+ free Lottie animations and grab any of them as
.lottieor.json, or create your own with Lottie Creator.
Contents
Introduction
A web component for rendering and playing Lottie and DotLottie animations in web applications.
What is dotLottie?
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".
Installation
npm install @lottiefiles/dotlottie-wcUsage
Via npm
After installation, you can use dotlottie-wc in your HTML file:
<dotlottie-wc src="https://lottie.host/4db68bbd-31f6-4cd8-84eb-189de081159a/IGmMCqhzpt.lottie" autoplay="true" loop="true"></dotlottie-wc>And import it in your JavaScript or TypeScript module:
import '@lottiefiles/dotlottie-wc';Via CDN
You can also use the component directly via a npm CDN:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>@lottiefiles/dotlottie-wc | Basic Example</title>
</head>
<body>
<dotlottie-wc src="https://lottie.host/4db68bbd-31f6-4cd8-84eb-189de081159a/IGmMCqhzpt.lottie" autoplay loop></dotlottie-wc>
<script type="module" src="https://unpkg.com/@lottiefiles/dotlottie-wc@latest/dist/dotlottie-wc.js"></script>
</body>
</html>APIs
Attributes
The dotlottie-wc component accepts all configuration attributes of DotLottie from @lottiefiles/dotlottie-web, allowing you to customize your animation as required.
| Attribute | Type | Description |
| ----------------- | --------------------- | ------------------------------------------------------------------------------------------------ |
| src | string | URL of the Lottie or DotLottie animation. |
| autoplay | boolean | Automatically start the animation. |
| loop | boolean | Loop the animation. |
| speed | number | Playback speed. |
| data | string | Animation data as a string or ArrayBuffer for .lottie animations. |
| segment | Array | Animation segment as an array of two numbers (start frame and end frame). |
| mode | string | Animation play mode (e.g., "forward", "bounce"). |
| backgroundColor | string | Background color of the canvas. Accepts 6-digit or 8-digit hex color string (e.g., "#000000FF"). |
| renderConfig | Object (RenderConfig) | Configuration for rendering the animation. |
RenderConfig
The renderConfig object accepts the following properties:
| Property name | Type | Required | Default | Description |
| ------------------ | ------ | :------: | ----------------------------- | ----------------------- |
| devicePixelRatio | number | | window.devicePixelRatio | 1 | The device pixel ratio. |
Properties
The dotlottie-wc exposes the following properties:
| Property name | Type | Description |
| ------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dotLottie | DotLottie | The dotLottie instance from DotLottie , allowing you to call methods and listen to events for more control over the animation. |
Every attribute above is also a live property on the element: reads go through to the player once it
is ready, and writes are forwarded to it — so framework property bindings (.speed=${} in Lit,
:speed in Vue) work the same as attributes:
const element = document.querySelector('dotlottie-wc');
element.dotLottie.setSpeed(3);
element.speed; // 3
element.mode; // 'forward' — the player default, even with no `mode` attribute
element.speed = 2; // same as element.dotLottie.setSpeed(2)Two exceptions: loopCount reports the configured maximum you passed in, not
dotLottie.loopCount (the number of loops completed so far), and reloading via a changed src or
data attribute always re-applies the values declared in your markup, not the live player state.
Custom WASM URL
By default, the player's WebAssembly file is loaded from a CDN. If you need to serve it from your own host (e.g. environments where CDN access is restricted), use setWasmUrl before any animation loads:
import { setWasmUrl } from '@lottiefiles/dotlottie-wc';
setWasmUrl('/js/dotlottie/dotlottie-player.wasm');The function is also exported from the CDN bundles, so it works when loading dist/dotlottie-wc.js or dist/dotlottie-worker-wc.js directly:
<script type="module">
import { setWasmUrl } from 'https://unpkg.com/@lottiefiles/dotlottie-wc@latest/dist/dotlottie-wc.js';
setWasmUrl('/js/dotlottie/dotlottie-player.wasm');
</script>You can find the matching dotlottie-player.wasm for your installed version inside the @lottiefiles/dotlottie-web package (dist/dotlottie-player.wasm) or on a npm CDN, e.g. https://unpkg.com/@lottiefiles/[email protected]/dist/dotlottie-player.wasm.
Development
Setup
npm installDev
npm run devBuild
npm run build