dotlottie-web
Implement Lottie animations using dotLottie runtimes (@lottiefiles/dotlottie-web and @lottiefiles/dotlottie-react). Use when building, debugging, or optimizing dotLottie or Lottie animations in web projects, including vanilla JS, React, and Next.js. Covers package selection, Web Workers, state machines, theming, dynamic slot overriding, performance best practices, and common patterns.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/LottieFiles/dotlottie-web with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/LottieFiles/dotlottie-web'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/lottiefiles--dotlottie-web)HTML
<a href="/listings/lottiefiles--dotlottie-web"><img src="/api/listings/lottiefiles--dotlottie-web/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Install the package for your framework, then drop in a few lines. The same player loads both Lottie `.json` and dotLottie `.lottie` files — just point `src` at either:
Vanilla JS
npm install @lottiefiles/dotlottie-web
<canvas id="canvas" style="width: 300px; height: 300px"></canvas>
import { DotLottie } from '@lottiefiles/dotlottie-web';
const dotLottie = new DotLottie({
canvas: document.getElementById('canvas'),
src: 'https://your-animation-url.lottie',
autoplay: true,
loop: true,
});<details> <summary><b>⚛️ React</b></summary>
npm install @lottiefiles/dotlottie-react
import { DotLottieReact } from '@lottiefiles/dotlottie-react';
const App = () => (
<DotLottieReact
src="path/to/animation.lottie"
loop
autoplay
/>
);</details>
<details> <summary><b>💚 Vue</b></summary>
npm install @lottiefiles/dotlottie-vue
<script setup>
import { DotLottieVue } from '@lottiefiles/dotlottie-vue';
</script>
<template>
<DotLottieVue
style="height: 500px; width: 500px"
autoplay
loop
src="https://path-to-lottie.lottie"
/>
</template></details>
<details> <summary><b>🧡 Svelte</b></summary>
npm install @lottiefiles/dotlottie-svelte
<script lang="ts">
import { DotLottieSvelte } from '@lottiefiles/dotlottie-svelte';
</script>
<DotLottieSvelte src="path/to/animation.lottie" loop autoplay /></details>
<details> <summary><b>🔵 Solid</b></summary>
npm install @lottiefiles/dotlottie-solid
import { DotLottieSolid } from '@lottiefiles/dotlottie-solid';
const App = () => (
<DotLottieSolid
src="path/to/animation.lottie"
loop
autoplay
/>
);</details>
<details> <summary><b>🌐 Web Component (drop-in, no build step)</b></summary>
<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>Or via npm:
npm install @lottiefiles/dotlottie-wc
import '@lottiefiles/dotlottie-wc';
</details>
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 544 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- ---
- name: dotlottie-web
- description: >-
- Implement Lottie animations using dotLottie runtimes (@lottiefiles/dotlottie-web
- and @lottiefiles/dotlottie-react). Use when building, debugging, or optimizing
- dotLottie or Lottie animations in web projects, including vanilla JS, React,
- and Next.js. Covers package selection, Web Workers, state machines, theming,
- dynamic slot overriding, performance best practices, and common patterns.
- license: MIT
- metadata:
- author: lottiefiles
- version: "1.0.0"
- source: "https://github.com/LottieFiles/dotlottie-web"
- ---
- # dotLottie Implementation Guidelines
- You are an expert at implementing Lottie animations using dotLottie runtimes. Follow these guidelines when working with dotLottie in web projects.
- ## Package Selection
- ### Use `@lottiefiles/dotlottie-web` when:
- * You need direct canvas control
- * Building framework-agnostic code
- * Maximum performance is critical
- * You want the smallest bundle
- ### Use `@lottiefiles/dotlottie-react` when:
- * Building React applications
- * You want declarative component API
- * You need React lifecycle integration
- ## Installation
- ```bash
- # Web (vanilla JS, Vue, Svelte, etc.)
- npm install @lottiefiles/dotlottie-web
- # React
- npm install @lottiefiles/dotlottie-react
- ```
- ## Basic Implementation
- ### Vanilla JavaScript
- ```typescript
- import { DotLottie } from '@lottiefiles/dotlottie-web';
- const dotLottie = new DotLottie({
- canvas: document.getElementById('canvas') as HTMLCanvasElement,
- src: 'https://example.com/animation.lottie',
- autoplay: true,
- loop: true,
- });
- ```
- ### React
- ```tsx
- import { DotLottieReact } from '@lottiefiles/dotlottie-react';
- function Animation() {
- return (
- <DotLottieReact
- src="https://example.com/animation.lottie"
- autoplay
- loop
- />
- );
- }
- ```
- ### React with Instance Control
- ```tsx
- import { useRef } from 'react';
- import { DotLottieReact } from '@lottiefiles/dotlottie-react';
- import type { DotLottie } from '@lottiefiles/dotlottie-web';
- function Animation() {
- const dotLottieRef = useRef<DotLottie | null>(null);
- return (
- <DotLottieReact
- src="https://example.com/animation.lottie"
- dotLottieRefCallback={(dotLottie) => (dotLottieRef.current = dotLottie)}
- />
- );
- }
- ```
- ## .lottie vs .json
- **Always prefer `.lottie` format over `.json`:**
- * Smaller file size (compressed)
- * Supports multiple animations in one file
- * Embedded assets (images, fonts)
- * State machines for interactivity
- * Theming with slots
- ## Web Workers (Recommended for Performance)
- Use `DotLottieWorker` to offload animation rendering to a Web Worker, keeping the main thread free for UI interactions:
- ### Basic Worker Usage
- ```typescript
- import { DotLottieWorker } from '@lottiefiles/dotlottie-web';
- const dotLottie = new DotLottieWorker({
- canvas: document.getElementById('canvas') as HTMLCanvasElement,
- src: 'https://example.com/animation.lottie',
- autoplay: true,
- loop: true,
- });
- ```
- ### Worker Grouping (Multiple Animations)
- By default, all `DotLottieWorker` instances share the same worker. Group animations into separate workers using `workerId`:
- ```typescript
- // Hero animation in its own worker
- const heroAnimation = new DotLottieWorker({
- canvas: heroCanvas,
- src: 'hero.lottie',
- workerId: 'hero-worker',
- });
- // UI animations share a different worker
- const buttonAnimation = new DotLottieWorker({
- canvas: buttonCanvas,
- src: 'button.lottie',
- workerId: 'ui-worker',
- });
- ```
- ### When to Use Workers
- * **Use `DotLottieWorker`** for:
- * Multiple simultaneous animations
- * Complex animations with many layers
- * Animations running alongside heavy JS operations
- * Mobile devices where main thread performance is critical
- * **Use regular `DotLottie`** for:
- * Single simple animations
- * When you need synchronous frame access
- * SSR environments (workers not available)
- ### React with Workers
- ```tsx
- import { DotLottieWorkerReact } from '@lottiefiles/dotlottie-react';
- function Animation() {
- return (
- <DotLottieWorkerReact
- src="animation.lottie"
- autoplay
- loop
- workerId="my-worker" // Optional: dedicate to specific worker
- />
- );
- }
- ```
- ## State Machines (Interactivity)
- State machines enable interactive animations without code. See the [State Machine Guide](https://github.com/LottieFiles/dotlottie-web/wiki/dotLottie-State-Machine-Guide) for details.
- ```typescript
- const dotLottie = new DotLottie({
- canvas,
- src: 'interactive.lottie', // Contains state machine
- autoplay: true,
- });
- // Fire events to trigger state transitions
- dotLottie.stateMachineFireEvent('click');
- dotLottie.stateMachineFireEvent('hover');
- dotLottie.stateMachineFireEvent('custom-event');
- // Set numeric/boolean/string inputs for state conditions
- // See: https://github.com/LottieFiles/dotlottie-web/wiki/dotLottie-State-Machine-Guide#working-with-inputs
- dotLottie.stateMachineSetNumericInput('progress', 0.5);
- dotLottie.stateMachineSetBooleanInput('isActive', true);
- dotLottie.stateMachineSetStringInput('mode', 'dark');
- ```
- ### State Machine Events
- * `click` - User click/tap
- * `hover` - Mouse enter
- * `unhover` - Mouse leave
- * `complete` - Animation finished
- * Custom events defined in the state machine
- ## Theming with Slots
- Slots allow runtime color/value customization. Themes follow the [dotLottie 2.0 spec](https://dotlottie.io/spec/2.0/#themes).
- ```typescript
- const dotLottie = new DotLottie({
- canvas,
- src: 'themed.lottie',
- themeId: 'dark-mode', // Use embedded theme by ID
- });
- // Or apply theme data directly (JSON string per dotLottie 2.0 spec)
- // See: https://dotlottie.io/spec/2.0/#themes
- dotLottie.setThemeData(JSON.stringify({
- rules: [
- { id: 'primary-color', value: [1, 0.34, 0.13] }, // RGB values 0-1
- ]
- }));
- ```
- ## Dynamic Slot Overriding
- Slots enable runtime customization of animated properties using typed APIs.
- Available slot types: color, scalar, vector, gradient, text, image.
- Key APIs: `getSlotIds()`, `getSlotType()`, `setColorSlot()`, `setScalarSlot()`,
- `setVectorSlot()`, `setGradientSlot()`, `setTextSlot()`, `resetSlot()`, `clearSlots()`.
- For complete API reference with code examples for each slot type, animated keyframes,
- resetting, bulk updates, common use cases (branding, dark mode, progress indicators),
- and React integration, see [Dynamic Slots Reference](references/dynamic-slots.md).
- ## Markers & Segments
- ### Playing Specific Segments
- ```typescript
- // Play frames 0-60
- dotLottie.setSegment(0, 60);
- dotLottie.play();
- // Play by marker name (defined in animation)
- dotLottie.setMarker('intro');
- dotLottie.play();
- ```
- ### Getting Markers
- ```typescript
- const markers = dotLottie.markers();
- // Returns: [{ name: 'intro', start: 0, end: 60 }, ...]
- ```
- ## Rendering a Specific Frame to an Image
- Set `autoplay: false` so playback doesn't advance past your target, then call `setFrame()` after `load`. `setFrame()` renders synchronously, so the canvas and `dotLottie.buffer` (RGBA `Uint8Array`) hold that exact frame immediately after the call.
- ### Browser
- ```typescript
- const dotLottie = new DotLottie({ canvas, src: 'animation.lottie', autoplay: false });
- dotLottie.addEventListener('load', () => {
- dotLottie.setFrame(42); // render frame 42
- const dataUrl = canvas.toDataURL('image/png'); // or canvas.toBlob(cb, 'image/png')
- });
- ```
- ### Node.js (`@napi-rs/canvas`)
- ```typescript
- import fs from 'node:fs';
- import { createCanvas } from '@napi-rs/canvas';
- const canvas = createCanvas(200, 200);
- const dotLottie = new DotLottie({
- canvas: canvas as unknown as HTMLCanvasElement,
- src: 'animation.lottie',
- autoplay: false,
- });
- dotLottie.addEventListener('load', async () => {
- dotLottie.setFrame(42);
- fs.writeFileSync('frame-42.png', await canvas.encode('png'));
- dotLottie.destroy();
- });
- ```
- For custom encoding, read raw RGBA pixels directly from `dotLottie.buffer` (length = `width × height × 4`).
- ## Event Handling
- ```typescript
- dotLottie.addEventListener('load', () => {
- console.log('Animation loaded');
- });
- dotLottie.addEventListener('play', () => {
- console.log('Playing');
- });
- dotLottie.addEventListener('complete', () => {
- console.log('Animation completed');
- });
- dotLottie.addEventListener('frame', ({ currentFrame }) => {
- console.log('Frame:', currentFrame);
- });
- // Clean up
- dotLottie.removeEventListener('load', handler);
- ```
- ## Performance Best Practices
- ### 1. Use Web Workers for Complex Animations
- ```typescript
- import { DotLottieWorker } from '@lottiefiles/dotlottie-web';
- // Offload rendering to worker thread
- const dotLottie = new DotLottieWorker({
- canvas,
- src: 'complex-animation.lottie',
- });
- ```
- ### 2. Lazy Load Animations
- ```typescript
- // Only load when visible
- const observer = new IntersectionObserver((entries) => {
- entries.forEach(entry => {
- if (entry.isIntersecting) {
- loadAnimation();
- observer.disconnect();
- }
- });
- });
- observer.observe(container);
- ```
- ### 3. Auto-Freeze is Enabled by Default
- DotLottie automatically freezes animations when they're not visible (offscreen). To disable this behavior:
- ```typescript
- const dotLottie = new DotLottie({
- canvas,
- src: 'animation.lottie',
- renderConfig: {
- freezeOnOffscreen: false, // Disable auto-freeze (not recommended)
- },
- });
- ```
- ### 4. Device Pixel Ratio
- By default, devicePixelRatio is set to 75% of the actual value for better performance. For full retina quality (with higher performance cost):
- ```typescript
- const dotLottie = new DotLottie({
- canvas,
- src: 'animation.lottie',
- renderConfig: {
- devicePixelRatio: window.devicePixelRatio, // Full retina (higher CPU/GPU)
- },
- });
- ```
- ### 5. Clean Up (Vanilla JS only)
- ```typescript
- // Always destroy when done (vanilla JS)
- dotLottie.destroy();
- ```
- **Note:** `DotLottieReact` handles cleanup automatically on unmount - no manual cleanup needed.
- ### 6. Frame Interpolation Control
- ```typescript
- const dotLottie = new DotLottie({
- canvas,
- src: 'animation.lottie',
- useFrameInterpolation: true, // Smooth playback (default)
- // useFrameInterpolation: false, // Match original AE frame rate
- });
- ```
- ## Multi-Animation Files
- A single `.lottie` file can contain multiple animations:
- ```typescript
- // Load specific animation by ID
- dotLottie.loadAnimation('animation-2');
- // Get all animation IDs
- const animations = dotLottie.manifest?.animations;
- // Returns: [{ id: 'animation-1' }, { id: 'animation-2' }]
- ```
- ## Canvas Sizing
- **Set canvas size via CSS styles** (recommended). DotLottie will automatically determine the optimal drawing area:
- ```html
- <canvas id="canvas" style="width: 400px; height: 400px;"></canvas>
- ```
- ### Auto-Resize to Container
- Use the `autoResize` render config to automatically resize when the container changes:
- ```typescript
- const dotLottie = new DotLottie({
- canvas,
- src: 'animation.lottie',
- renderConfig: {
- autoResize: true, // Canvas resizes to fit container
- },
- });
- ```
- ## Common Patterns
- ### Play on Hover
- ```typescript
- canvas.addEventListener('mouseenter', () => dotLottie.play());
- canvas.addEventListener('mouseleave', () => dotLottie.pause());
- ```
- ### Play on Click (Once)
- ```typescript
- canvas.addEventListener('click', () => {
- dotLottie.setFrame(0);
- dotLottie.setLoop(false);
- dotLottie.play();
- });
- ```
- ### Scrub with Scroll
- ```typescript
- window.addEventListener('scroll', () => {
- const progress = window.scrollY / (document.body.scrollHeight - window.innerHeight);
- const frame = progress * dotLottie.totalFrames;
- dotLottie.setFrame(frame);
- });
- ```
- ### Loading States (React)
- ```tsx
- function Animation() {
- const [isLoaded, setIsLoaded] = useState(false);
- return (
- <>
- {!isLoaded && <Skeleton />}
- <DotLottieReact
- src="animation.lottie"
- style={{ opacity: isLoaded ? 1 : 0 }}
- dotLottieRefCallback={(dotLottie) => {
- dotLottie.addEventListener('load', () => setIsLoaded(true));
- }}
- />
- </>
- );
- }
- ```
- ### Responsive Animation
- ```tsx
- function ResponsiveAnimation() {
- return (
- <DotLottieReact
- src="animation.lottie"
- autoplay
- loop
- style={{ width: '100%', maxWidth: '400px' }}
- renderConfig={{ autoResize: true }}
- />
- );
- }
- ```
- ## Debugging
- ```typescript
- // Check if loaded
- console.log('Loaded:', dotLottie.isLoaded);
- // Get animation info
- console.log('Duration:', dotLottie.duration);
- console.log('Total Frames:', dotLottie.totalFrames);
- console.log('Current Frame:', dotLottie.currentFrame);
- console.log('Is Playing:', dotLottie.isPlaying);
- console.log('Loop:', dotLottie.loop);
- console.log('Speed:', dotLottie.speed);
- // Get manifest (for .lottie files)
- console.log('Manifest:', dotLottie.manifest);
- ```
- ## Error Handling
- ```typescript
- dotLottie.addEventListener('loadError', (error) => {
- console.error('Failed to load animation:', error);
- // Show fallback UI
- });
- ```
- ## SSR / Next.js Considerations
- dotLottie requires browser APIs. For SSR frameworks:
- ```tsx
- import dynamic from 'next/dynamic';
- const DotLottieReact = dynamic(
- () => import('@lottiefiles/dotlottie-react').then(mod => mod.DotLottieReact),
- { ssr: false }
- );
- function Animation() {
- return <DotLottieReact src="animation.lottie" autoplay loop />;
- }
- ```
- ## Resources
- * Documentation: [https://developers.lottiefiles.com/docs/dotlottie-player](https://developers.lottiefiles.com/docs/dotlottie-player)
- * State Machine Guide: [https://github.com/LottieFiles/dotlottie-web/wiki/dotLottie-State-Machine-Guide](https://github.com/LottieFiles/dotlottie-web/wiki/dotLottie-State-Machine-Guide)
- * GitHub: [https://github.com/LottieFiles/dotlottie-web](https://github.com/LottieFiles/dotlottie-web)
- * dotLottie 2.0 Spec: [https://dotlottie.io/spec/2.0/](https://dotlottie.io/spec/2.0/)
- * Create .lottie files: [https://lottiefiles.com](https://lottiefiles.com) or [https://creators.lottiefiles.com](https://creators.lottiefiles.com)
README.md · README · 363 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- 
- 
- 
- 
- 
- <p align="center">
- <img src="https://lottie.host/43f43646-b018-4d72-a96b-02a929cd9727/gARxdIetbE.svg" alt="dotLottie Web" width="550" />
- </p>
- <h1 align="center">dotLottie Web</h1>
- <p align="center">
- The official LottieFiles player for <b>Lottie</b> (<code>.json</code>) and
- <b>dotLottie</b> (<code>.lottie</code>) animations on the web — a Rust + WASM core
- powered by <a href="https://github.com/thorvg/thorvg">ThorVG</a>, with Software,
- WebGL2, and WebGPU rendering backends and full
- <a href="https://lottiefiles.com/dotlottie">dotLottie v2</a> support (theming, state machines,
- and audio).
- </p>
- <p align="center">
- <a href="https://lottiefiles.github.io/dotlottie-web/"><b>🌐 Live Viewer</b></a> ·
- <a href="https://lottiefiles.github.io/dotlottie-web/perf-test"><b>📊 Perf Playground</b></a> ·
- <a href="https://developers.lottiefiles.com/docs/dotlottie-player/dotlottie-web/"><b>📚 Docs</b></a> ·
- <a href="https://github.com/LottieFiles/dotlottie-rs"><b>🦀 dotLottie-rs</b></a>
- </p>
- # Why dotLottie Web
- * 📦 **Lottie + dotLottie, one player** — point `src` at a classic Lottie [`.json`](https://lottiefiles.github.io/lottie-docs/) or a [`.lottie`](https://lottiefiles.com/dotlottie) archive. The `.lottie` format bundles multiple animations, themes, state machines, and embedded assets into a single compressed file.
- * 🦀 **Rust + WASM core** — powered by [`dotlottie-rs`](https://github.com/LottieFiles/dotlottie-rs), the same engine that ships in iOS, Android, and native dotLottie players. One battle-tested implementation across every platform.
- * 🎨 **ThorVG renderer** — an industrial-grade vector graphics engine with the broadest Lottie feature coverage of any web renderer. See the [ThorVG Lottie support matrix](https://github.com/thorvg/thorvg/wiki/Lottie-Support).
- * ⚡ **Three rendering backends** — Software (Canvas2D), WebGL2, and WebGPU (experimental). Switch with a one-line import change — same `DotLottie` class everywhere.
- * 📁 **dotLottie v2 ready** — first-class **theming**, interactive **state machines**, and **audio** in a single `.lottie` file. No userland wiring required.
- * 🧵 **Off-main-thread** — `DotLottieWorker` renders on a Web Worker with `OffscreenCanvas`, keeping your UI buttery-smooth even with dozens of animations.
- * ⚛️ **6 first-party SDKs** — Vanilla JS, [React](packages/react/README.md), [Vue](packages/vue/README.md), [Svelte](packages/svelte/README.md), [Solid](packages/solid/README.md), and a [Web Component](packages/wc/README.md). Plus SSR-safe (Next.js example included) and Node.js 18+ support.
- * 🎛️ **Rich runtime control** — themes, slots (color/scalar/vector/gradient/text/image), markers, segments, layouts (`fit` + `align`), playback modes (forward/reverse/bounce), frame interpolation, 25+ typed events.
- ## Quick Start
- Install the package for your framework, then drop in a few lines. The same player loads both Lottie `.json` and dotLottie `.lottie` files — just point `src` at either:
- ### Vanilla JS
- ```bash
- npm install @lottiefiles/dotlottie-web
- ```
- ```html
- <canvas id="canvas" style="width: 300px; height: 300px"></canvas>
- ```
- ```js
- import { DotLottie } from '@lottiefiles/dotlottie-web';
- const dotLottie = new DotLottie({
- canvas: document.getElementById('canvas'),
- src: 'https://your-animation-url.lottie',
- autoplay: true,
- loop: true,
- });
- ```
- <details>
- <summary><b>⚛️ React</b></summary>
- ```bash
- npm install @lottiefiles/dotlottie-react
- ```
- ```jsx
- import { DotLottieReact } from '@lottiefiles/dotlottie-react';
- const App = () => (
- <DotLottieReact
- src="path/to/animation.lottie"
- loop
- autoplay
- />
- );
- ```
- </details>
- <details>
- <summary><b>💚 Vue</b></summary>
- ```bash
- npm install @lottiefiles/dotlottie-vue
- ```
- ```vue
- <script setup>
- import { DotLottieVue } from '@lottiefiles/dotlottie-vue';
- </script>
- <template>
- <DotLottieVue
- style="height: 500px; width: 500px"
- autoplay
- loop
- src="https://path-to-lottie.lottie"
- />
- </template>
- ```
- </details>
- <details>
- <summary><b>🧡 Svelte</b></summary>
- ```bash
- npm install @lottiefiles/dotlottie-svelte
- ```
- ```svelte
- <script lang="ts">
- import { DotLottieSvelte } from '@lottiefiles/dotlottie-svelte';
- </script>
- <DotLottieSvelte src="path/to/animation.lottie" loop autoplay />
- ```
- </details>
- <details>
- <summary><b>🔵 Solid</b></summary>
- ```bash
- npm install @lottiefiles/dotlottie-solid
- ```
- ```jsx
- import { DotLottieSolid } from '@lottiefiles/dotlottie-solid';
- const App = () => (
- <DotLottieSolid
- src="path/to/animation.lottie"
- loop
- autoplay
- />
- );
- ```
- </details>
- <details>
- <summary><b>🌐 Web Component (drop-in, no build step)</b></summary>
- ```html
- <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>
- ```
- Or via npm:
- ```bash
- npm install @lottiefiles/dotlottie-wc
- ```
- ```js
- import '@lottiefiles/dotlottie-wc';
- ```
- </details>
- ## Features
- ### 🤖 Interactive State Machines
- dotLottie v2 ships **state machines** built into the file format — no JS glue required. Define states, transitions, and inputs in a single `.lottie` and drive them at runtime through pointer events, custom events, or input values.
- ```js
- const dotLottie = new DotLottie({
- canvas: document.getElementById('canvas'),
- src: 'interactive-button.lottie',
- stateMachineId: 'main',
- autoplay: true,
- });
- ```
- The player exposes typed events for `stateMachineStart`, `stateMachineTransition`, `stateMachineStateEntered`, custom events, and input changes — perfect for wiring animations into your UI logic.
- ### 🎨 Runtime Theming
- Switch palettes, animate gradients, swap text, or replace images at runtime — without re-exporting from After Effects. Themes can be embedded in the `.lottie` manifest or supplied programmatically.
- ```js
- // Use a theme defined in the .lottie manifest
- dotLottie.setTheme('dark');
- // Or supply a theme object at runtime
- dotLottie.setThemeData({
- rules: [
- { id: 'primary', type: 'Color', value: [0.9, 0.2, 0.4, 1.0] },
- ],
- });
- ```
- The full `Theme` type covers color, scalar, position, vector, gradient, image, and text rules — all keyframe-aware.
- ### 🔊 Audio Support
- `dotLottie` files can carry embedded audio tracks alongside the animation timeline — handy for UI sound effects, onboarding flows, or interactive characters. Audio is decoded and played in lockstep with the animation timeline.
- > Audio is an experimental feature in `dotlottie-rs`. Browser autoplay policies still apply — initiate playback from a user gesture.
- ### 🧵 Off-Main-Thread Rendering
- For pages with many animations, swap `DotLottie` for `DotLottieWorker`. Identical API, but rendering happens on a Web Worker with an `OffscreenCanvas`, freeing the main thread for layout, scrolling, and your app code.
- ```js
- import { DotLottieWorker } from '@lottiefiles/dotlottie-web';
- const player = new DotLottieWorker({
- canvas: document.getElementById('canvas'),
- src: 'animation.lottie',
- autoplay: true,
- loop: true,
- workerId: 'shared-pool', // optional: share one worker across many instances
- });
- ```
- All `DotLottieWorker` methods are async (Promise-returning) since they cross a worker boundary.
- ### ⚡ Hardware-Accelerated Rendering
- The default Software backend works everywhere. For demanding workloads — many concurrent animations, large canvases, complex masks — opt in to GPU rendering via subpath imports:
- ```js
- // WebGL2 — broadly supported
- import { DotLottie } from '@lottiefiles/dotlottie-web/webgl';
- // WebGPU — experimental, modern Chromium / Safari TP
- import { DotLottie } from '@lottiefiles/dotlottie-web/webgpu';
- ```
- The class name (`DotLottie`) and API surface are identical across all three backends, so swapping renderers is a one-line change. Each backend ships its own optimized WASM build via [package.json conditional exports](packages/web/package.json).
- > Want to see the difference on your own hardware? The hosted [perf-test page](https://lottiefiles.github.io/dotlottie-web/perf-test) compares Software vs WebGL vs WebGPU vs Skottie/CanvasKit head-to-head.
- ### 🖼️ More built-in capabilities
- * **Multi-animation `.lottie` files** — `animationId` config + `loadAnimation(id)` to switch between bundled animations
- * **Named markers** — `setMarker(name)` and `markers()` to play AE-defined segments
- * **Frame segments** — `setSegment(start, end)` for arbitrary frame ranges
- * **Layout** — `fit` (`contain` / `cover` / `fill` / `fit-width` / `fit-height` / `none`) + normalized `align: [x, y]`
- * **Slots** — bind dynamic data to color, scalar, vector, gradient, text, and image slots at runtime
- * **Playback modes** — `forward` / `reverse` / `bounce` / `reverse-bounce` with configurable loop counts
- * **Frame interpolation** — smooth subframe playback (default on) or pinned to the original AE frame rate
- * **Freeze on offscreen** — automatically pause rendering when the canvas leaves the viewport
- * **25+ typed events** — `play`, `pause`, `frame`, `complete`, `loop`, `load`, `loadError`, `freeze`, plus the full state-machine event suite
- ## Packages
- All packages render both Lottie (`.json`) and dotLottie (`.lottie`) animations.
- | Package | Description |
- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
- | **[@lottiefiles/dotlottie-web](packages/web/README.md)** | Core Lottie & dotLottie player — Rust/WASM via dotlottie-rs, Canvas2D / WebGL / WebGPU, Node-isomorphic |
- | **[@lottiefiles/dotlottie-react](packages/react/README.md)** | React component for Lottie & dotLottie |
- | **[@lottiefiles/dotlottie-vue](packages/vue/README.md)** | Vue 3 component for Lottie & dotLottie |
- | **[@lottiefiles/dotlottie-svelte](packages/svelte/README.md)** | Svelte component for Lottie & dotLottie |
- | **[@lottiefiles/dotlottie-solid](packages/solid/README.md)** | Solid component for Lottie & dotLottie |
- | **[@lottiefiles/dotlottie-wc](packages/wc/README.md)** | Framework-agnostic Web Component for Lottie & dotLottie |
- Each package README contains its full API reference, prop tables, and event documentation.
- ## dotLottie Viewer
- A hosted companion app at **[lottiefiles.github.io/dotlottie-web](https://lottiefiles.github.io/dotlottie-web/)** for inspecting, debugging, and benchmarking animations:
- | Page | What it does |
- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | [**Home**](https://lottiefiles.github.io/dotlottie-web/) | Drop a `.lottie` or `.json` file to preview rendering and inspect manifest details |
- | [**Playground**](https://lottiefiles.github.io/dotlottie-web/playground) | Interactive editor for player config, themes, markers, and animation switching |
- | [**Performance**](https://lottiefiles.github.io/dotlottie-web/perf-test) | Stress test across 40+ animations — **compare Software / WebGL / WebGPU / Skottie head-to-head on your own hardware**, with seedable runs for reproducibility |
- | [**List**](https://lottiefiles.github.io/dotlottie-web/list) | Gallery of curated animations |
- | [**Embed**](https://lottiefiles.github.io/dotlottie-web/embed) | Embedding patterns and demos |
- Source: [`apps/viewer/`](apps/viewer/).
- ## Live Examples (CodePen)
- **[@lottiefiles/dotlottie-web](packages/web/README.md)** —
- [Getting Started](https://codepen.io/lottiefiles/pen/JjzJZmL) ·
- [Playback Controls](https://codepen.io/lottiefiles/pen/dyrRKwg) ·
- [Dynamic Loading](https://codepen.io/lottiefiles/pen/JjzJZgB) ·
- [Worker](https://codepen.io/lottiefiles/pen/VwJZPrQ) ·
- [Multi Animations](https://codepen.io/lottiefiles/pen/wvOxdRa) ·
- [Advanced Layout](https://codepen.io/lottiefiles/pen/LYvZveR) ·
- [Named Markers](https://codepen.io/lottiefiles/pen/RwOROKp) ·
- [Theming](https://codepen.io/lottiefiles/pen/BaEzEeq) ·
- [Interactivity](https://codepen.io/lottiefiles/pen/VwJvdRN)
- **[@lottiefiles/dotlottie-react](packages/react/README.md)** —
- [Getting Started](https://codepen.io/lottiefiles/pen/vYPJpBN) ·
- [Custom Controls](https://codepen.io/lottiefiles/pen/WNmEdxd)
- **[@lottiefiles/dotlottie-vue](packages/vue/README.md)** —
- [Getting Started](https://codepen.io/lottiefiles/pen/yLwgeoJ)
- ## Local Examples
- Runnable example apps in [`examples/`](examples/):
- | Example | Package | Highlights |
- | ------------------------------ | ---------------------------------------- | --------------------------------------------- |
- | [web](examples/web/) | `@lottiefiles/dotlottie-web` | State machines, themes, segments, layout |
- | [web-node](examples/web-node/) | `@lottiefiles/dotlottie-web` (Node.js) | Server-side rendering to a buffer |
- | [react](examples/react/) | `@lottiefiles/dotlottie-react` | Renderer selection (canvas/webgl/webgpu) |
- | [vue](examples/vue/) | `@lottiefiles/dotlottie-vue` | Theme toggling, ref/event patterns |
- | [solid](examples/solid/) | `@lottiefiles/dotlottie-solid` | Signal-based state, theme/animation switching |
- | [wc](examples/wc/) | `@lottiefiles/dotlottie-wc` | Web Component usage and event delegation |
- | [next](examples/next/) | `@lottiefiles/dotlottie-react` (Next.js) | SSR-safe rendering with the App Router |
- ```bash
- pnpm install && pnpm run build
- cd examples/web
- pnpm run dev
- ```
- ## Browser & Runtime Support
- **Required:** WebAssembly · Canvas 2D · Fetch API
- **Optional (enhances perf):** Web Workers · OffscreenCanvas · WebGL2 (for `/webgl`) · WebGPU (for `/webgpu`)
- | Browser | Minimum version |
- | ---------- | --------------- |
- | Chrome | 57+ (Mar 2017) |
- | Firefox | 52+ (Mar 2017) |
- | Safari | 11+ (Sep 2017) |
- | Edge | 16+ (Oct 2017) |
- | iOS Safari | 11+ (Sep 2017) |
- **Node.js:** 18+ — `@lottiefiles/dotlottie-web` is isomorphic and runs server-side for thumbnail generation, frame extraction, or static rendering.
- ## Development
- **Prerequisites:** Node.js 22+, pnpm 10+
- ```bash
- git clone https://github.com/LottieFiles/dotlottie-web.git
- cd dotlottie-web
- pnpm install
- pnpm run build # Build all packages
- pnpm run dev # Watch mode
- pnpm run test # Run tests
- pnpm run lint # Lint
- pnpm run format # Format
- ```
- ## Contributing
- Contributions are welcome! Read the [Contributing Guidelines](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) before opening an issue or PR.
- ## License
- [MIT](LICENSE) © [LottieFiles](https://www.lottiefiles.com)
scripts/dev-release-report.mjs · Bundled script · 158 lines · 1 finding marked
- // Reports a published dev snapshot: writes the job summary and upserts a sticky
- // comment on the branch's open PR. Run after `changeset publish` in release.yml.
- //
- // Usage:
- // node scripts/dev-release-report.mjs
- // node scripts/dev-release-report.mjs --dry-run # print the comment, call no APIs
- import fs from 'node:fs/promises';
- import path from 'node:path';
- import { fileURLToPath } from 'node:url';
- const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
- const MARKER = '<!-- dev-release-snapshot -->';
- const BOT = 'github-actions[bot]';
- const dryRun = process.argv.includes('--dry-run');
- const {
- GITHUB_TOKEN,
- GITHUB_REPOSITORY,
- GITHUB_REF_NAME,
- GITHUB_SHA,
- GITHUB_RUN_ID,
- GITHUB_SERVER_URL = 'https://github.com',
- GITHUB_STEP_SUMMARY,
- } = process.env;
- /** Every publishable package in the workspace, so a new package is never silently skipped. */
- async function publishedPackages() {
- const dirs = await fs.readdir(path.join(ROOT, 'packages'));
- const pkgs = await Promise.all(
- dirs.map(async (dir) => {
- const manifest = path.join(ROOT, 'packages', dir, 'package.json');
- const pkg = JSON.parse(await fs.readFile(manifest, 'utf-8'));
- return pkg.private ? null : pkg;
- }),
- );
- return pkgs.filter(Boolean).sort((a, b) => a.name.localeCompare(b.name));
- }
- function renderComment(packages, version) {
- // The web package is what people actually install; the rest go in a fold.
- const primary = packages.find((pkg) => pkg.name.endsWith('/dotlottie-web')) ?? packages[0];
- const rest = packages.filter((pkg) => pkg !== primary);
- const lines = [
- MARKER,
- '### 🚀 Dev release published',
- '',
- `All packages published at \`${version}\` under the \`dev\` dist-tag.`,
- '',
- '```sh',
- `npm i ${primary.name}@${version}`,
- '```',
- '',
- ];
- if (rest.length > 0) {
- lines.push(
- '<details><summary>Other packages</summary>',
- '',
- '```sh',
- ...rest.map((pkg) => `npm i ${pkg.name}@${version}`),
- '```',
- '',
- '</details>',
- '',
- );
- }
- const runUrl = `${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}`;
- lines.push(
- 'Published to both npmjs and GitHub Packages, so it resolves regardless of which',
- 'registry your `.npmrc` points the `@lottiefiles` scope at.',
- Dismissed after review: Reads a credential file in a script that also sends data over the network
- Line 77 on GitHub
- '',
- `Built from \`${GITHUB_REF_NAME}\` @ \`${GITHUB_SHA}\` · [run](${runUrl})`,
- );
- return lines.join('\n');
- }
- async function api(endpoint, options = {}) {
- const response = await fetch(`https://api.github.com${endpoint}`, {
- ...options,
- headers: {
- accept: 'application/vnd.github+json',
- authorization: `Bearer ${GITHUB_TOKEN}`,
- 'x-github-api-version': '2022-11-28',
- ...options.headers,
- },
- });
- if (!response.ok) {
- throw new Error(
- `GitHub API ${options.method ?? 'GET'} ${endpoint} failed: ${response.status} ${await response.text()}`,
- );
- }
- return response.json();
- }
- /** The open PR for this branch, or null when the release was cut from a bare branch. */
- async function findOpenPullRequest() {
- const [owner] = GITHUB_REPOSITORY.split('/');
- const query = new URLSearchParams({ head: `${owner}:${GITHUB_REF_NAME}`, state: 'open' });
- const [pr] = await api(`/repos/${GITHUB_REPOSITORY}/pulls?${query}`);
- return pr ?? null;
- }
- /**
- * Our own previous report, if any. Matching on the marker alone is not enough:
- * anyone quoting the comment copies the marker with it, and we must not edit
- * a human's comment.
- */
- async function findPreviousComment(prNumber) {
- const comments = await api(`/repos/${GITHUB_REPOSITORY}/issues/${prNumber}/comments?per_page=100`);
- return comments.find((comment) => comment.user.login === BOT && comment.body.startsWith(MARKER)) ?? null;
- }
- const packages = await publishedPackages();
- const { version } = packages.find((pkg) => pkg.name.endsWith('/dotlottie-web')) ?? packages[0];
- const body = renderComment(packages, version);
- if (dryRun) {
- console.log(body);
- process.exit(0);
- }
- if (GITHUB_STEP_SUMMARY) await fs.appendFile(GITHUB_STEP_SUMMARY, `${body}\n`);
- const pr = await findOpenPullRequest();
- if (!pr) {
- console.log(`Published ${version}, but '${GITHUB_REF_NAME}' has no open PR — nothing to comment on.`);
- process.exit(0);
- }
- const previous = await findPreviousComment(pr.number);
- // Upsert, so repeated dev releases on one PR don't pile up comments.
- if (previous) {
- await api(`/repos/${GITHUB_REPOSITORY}/issues/comments/${previous.id}`, {
- method: 'PATCH',
- body: JSON.stringify({ body }),
- });
- console.log(`Updated comment ${previous.id} on PR #${pr.number} with ${version}`);
- } else {
- await api(`/repos/${GITHUB_REPOSITORY}/issues/${pr.number}/comments`, {
- method: 'POST',
- body: JSON.stringify({ body }),
- });
- console.log(`Commented on PR #${pr.number} with ${version}`);
- }
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.