Skip to content
Back to search

dotlottie-web

SkillWorks with Claude CodeGitHub

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lottiefiles--dotlottie-web/badge.svg)](/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

i

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.

  1. ---
  2. name: dotlottie-web
  3. description: >-
  4. Implement Lottie animations using dotLottie runtimes (@lottiefiles/dotlottie-web
  5. and @lottiefiles/dotlottie-react). Use when building, debugging, or optimizing
  6. dotLottie or Lottie animations in web projects, including vanilla JS, React,
  7. and Next.js. Covers package selection, Web Workers, state machines, theming,
  8. dynamic slot overriding, performance best practices, and common patterns.
  9. license: MIT
  10. metadata:
  11. author: lottiefiles
  12. version: "1.0.0"
  13. source: "https://github.com/LottieFiles/dotlottie-web"
  14. ---
  15. # dotLottie Implementation Guidelines
  16. You are an expert at implementing Lottie animations using dotLottie runtimes. Follow these guidelines when working with dotLottie in web projects.
  17. ## Package Selection
  18. ### Use `@lottiefiles/dotlottie-web` when:
  19. * You need direct canvas control
  20. * Building framework-agnostic code
  21. * Maximum performance is critical
  22. * You want the smallest bundle
  23. ### Use `@lottiefiles/dotlottie-react` when:
  24. * Building React applications
  25. * You want declarative component API
  26. * You need React lifecycle integration
  27. ## Installation
  28. ```bash
  29. # Web (vanilla JS, Vue, Svelte, etc.)
  30. npm install @lottiefiles/dotlottie-web
  31. # React
  32. npm install @lottiefiles/dotlottie-react
  33. ```
  34. ## Basic Implementation
  35. ### Vanilla JavaScript
  36. ```typescript
  37. import { DotLottie } from '@lottiefiles/dotlottie-web';
  38. const dotLottie = new DotLottie({
  39. canvas: document.getElementById('canvas') as HTMLCanvasElement,
  40. src: 'https://example.com/animation.lottie',
  41. autoplay: true,
  42. loop: true,
  43. });
  44. ```
  45. ### React
  46. ```tsx
  47. import { DotLottieReact } from '@lottiefiles/dotlottie-react';
  48. function Animation() {
  49. return (
  50. <DotLottieReact
  51. src="https://example.com/animation.lottie"
  52. autoplay
  53. loop
  54. />
  55. );
  56. }
  57. ```
  58. ### React with Instance Control
  59. ```tsx
  60. import { useRef } from 'react';
  61. import { DotLottieReact } from '@lottiefiles/dotlottie-react';
  62. import type { DotLottie } from '@lottiefiles/dotlottie-web';
  63. function Animation() {
  64. const dotLottieRef = useRef<DotLottie | null>(null);
  65. return (
  66. <DotLottieReact
  67. src="https://example.com/animation.lottie"
  68. dotLottieRefCallback={(dotLottie) => (dotLottieRef.current = dotLottie)}
  69. />
  70. );
  71. }
  72. ```
  73. ## .lottie vs .json
  74. **Always prefer `.lottie` format over `.json`:**
  75. * Smaller file size (compressed)
  76. * Supports multiple animations in one file
  77. * Embedded assets (images, fonts)
  78. * State machines for interactivity
  79. * Theming with slots
  80. ## Web Workers (Recommended for Performance)
  81. Use `DotLottieWorker` to offload animation rendering to a Web Worker, keeping the main thread free for UI interactions:
  82. ### Basic Worker Usage
  83. ```typescript
  84. import { DotLottieWorker } from '@lottiefiles/dotlottie-web';
  85. const dotLottie = new DotLottieWorker({
  86. canvas: document.getElementById('canvas') as HTMLCanvasElement,
  87. src: 'https://example.com/animation.lottie',
  88. autoplay: true,
  89. loop: true,
  90. });
  91. ```
  92. ### Worker Grouping (Multiple Animations)
  93. By default, all `DotLottieWorker` instances share the same worker. Group animations into separate workers using `workerId`:
  94. ```typescript
  95. // Hero animation in its own worker
  96. const heroAnimation = new DotLottieWorker({
  97. canvas: heroCanvas,
  98. src: 'hero.lottie',
  99. workerId: 'hero-worker',
  100. });
  101. // UI animations share a different worker
  102. const buttonAnimation = new DotLottieWorker({
  103. canvas: buttonCanvas,
  104. src: 'button.lottie',
  105. workerId: 'ui-worker',
  106. });
  107. ```
  108. ### When to Use Workers
  109. * **Use `DotLottieWorker`** for:
  110. * Multiple simultaneous animations
  111. * Complex animations with many layers
  112. * Animations running alongside heavy JS operations
  113. * Mobile devices where main thread performance is critical
  114. * **Use regular `DotLottie`** for:
  115. * Single simple animations
  116. * When you need synchronous frame access
  117. * SSR environments (workers not available)
  118. ### React with Workers
  119. ```tsx
  120. import { DotLottieWorkerReact } from '@lottiefiles/dotlottie-react';
  121. function Animation() {
  122. return (
  123. <DotLottieWorkerReact
  124. src="animation.lottie"
  125. autoplay
  126. loop
  127. workerId="my-worker" // Optional: dedicate to specific worker
  128. />
  129. );
  130. }
  131. ```
  132. ## State Machines (Interactivity)
  133. 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.
  134. ```typescript
  135. const dotLottie = new DotLottie({
  136. canvas,
  137. src: 'interactive.lottie', // Contains state machine
  138. autoplay: true,
  139. });
  140. // Fire events to trigger state transitions
  141. dotLottie.stateMachineFireEvent('click');
  142. dotLottie.stateMachineFireEvent('hover');
  143. dotLottie.stateMachineFireEvent('custom-event');
  144. // Set numeric/boolean/string inputs for state conditions
  145. // See: https://github.com/LottieFiles/dotlottie-web/wiki/dotLottie-State-Machine-Guide#working-with-inputs
  146. dotLottie.stateMachineSetNumericInput('progress', 0.5);
  147. dotLottie.stateMachineSetBooleanInput('isActive', true);
  148. dotLottie.stateMachineSetStringInput('mode', 'dark');
  149. ```
  150. ### State Machine Events
  151. * `click` - User click/tap
  152. * `hover` - Mouse enter
  153. * `unhover` - Mouse leave
  154. * `complete` - Animation finished
  155. * Custom events defined in the state machine
  156. ## Theming with Slots
  157. Slots allow runtime color/value customization. Themes follow the [dotLottie 2.0 spec](https://dotlottie.io/spec/2.0/#themes).
  158. ```typescript
  159. const dotLottie = new DotLottie({
  160. canvas,
  161. src: 'themed.lottie',
  162. themeId: 'dark-mode', // Use embedded theme by ID
  163. });
  164. // Or apply theme data directly (JSON string per dotLottie 2.0 spec)
  165. // See: https://dotlottie.io/spec/2.0/#themes
  166. dotLottie.setThemeData(JSON.stringify({
  167. rules: [
  168. { id: 'primary-color', value: [1, 0.34, 0.13] }, // RGB values 0-1
  169. ]
  170. }));
  171. ```
  172. ## Dynamic Slot Overriding
  173. Slots enable runtime customization of animated properties using typed APIs.
  174. Available slot types: color, scalar, vector, gradient, text, image.
  175. Key APIs: `getSlotIds()`, `getSlotType()`, `setColorSlot()`, `setScalarSlot()`,
  176. `setVectorSlot()`, `setGradientSlot()`, `setTextSlot()`, `resetSlot()`, `clearSlots()`.
  177. For complete API reference with code examples for each slot type, animated keyframes,
  178. resetting, bulk updates, common use cases (branding, dark mode, progress indicators),
  179. and React integration, see [Dynamic Slots Reference](references/dynamic-slots.md).
  180. ## Markers & Segments
  181. ### Playing Specific Segments
  182. ```typescript
  183. // Play frames 0-60
  184. dotLottie.setSegment(0, 60);
  185. dotLottie.play();
  186. // Play by marker name (defined in animation)
  187. dotLottie.setMarker('intro');
  188. dotLottie.play();
  189. ```
  190. ### Getting Markers
  191. ```typescript
  192. const markers = dotLottie.markers();
  193. // Returns: [{ name: 'intro', start: 0, end: 60 }, ...]
  194. ```
  195. ## Rendering a Specific Frame to an Image
  196. 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.
  197. ### Browser
  198. ```typescript
  199. const dotLottie = new DotLottie({ canvas, src: 'animation.lottie', autoplay: false });
  200. dotLottie.addEventListener('load', () => {
  201. dotLottie.setFrame(42); // render frame 42
  202. const dataUrl = canvas.toDataURL('image/png'); // or canvas.toBlob(cb, 'image/png')
  203. });
  204. ```
  205. ### Node.js (`@napi-rs/canvas`)
  206. ```typescript
  207. import fs from 'node:fs';
  208. import { createCanvas } from '@napi-rs/canvas';
  209. const canvas = createCanvas(200, 200);
  210. const dotLottie = new DotLottie({
  211. canvas: canvas as unknown as HTMLCanvasElement,
  212. src: 'animation.lottie',
  213. autoplay: false,
  214. });
  215. dotLottie.addEventListener('load', async () => {
  216. dotLottie.setFrame(42);
  217. fs.writeFileSync('frame-42.png', await canvas.encode('png'));
  218. dotLottie.destroy();
  219. });
  220. ```
  221. For custom encoding, read raw RGBA pixels directly from `dotLottie.buffer` (length = `width × height × 4`).
  222. ## Event Handling
  223. ```typescript
  224. dotLottie.addEventListener('load', () => {
  225. console.log('Animation loaded');
  226. });
  227. dotLottie.addEventListener('play', () => {
  228. console.log('Playing');
  229. });
  230. dotLottie.addEventListener('complete', () => {
  231. console.log('Animation completed');
  232. });
  233. dotLottie.addEventListener('frame', ({ currentFrame }) => {
  234. console.log('Frame:', currentFrame);
  235. });
  236. // Clean up
  237. dotLottie.removeEventListener('load', handler);
  238. ```
  239. ## Performance Best Practices
  240. ### 1. Use Web Workers for Complex Animations
  241. ```typescript
  242. import { DotLottieWorker } from '@lottiefiles/dotlottie-web';
  243. // Offload rendering to worker thread
  244. const dotLottie = new DotLottieWorker({
  245. canvas,
  246. src: 'complex-animation.lottie',
  247. });
  248. ```
  249. ### 2. Lazy Load Animations
  250. ```typescript
  251. // Only load when visible
  252. const observer = new IntersectionObserver((entries) => {
  253. entries.forEach(entry => {
  254. if (entry.isIntersecting) {
  255. loadAnimation();
  256. observer.disconnect();
  257. }
  258. });
  259. });
  260. observer.observe(container);
  261. ```
  262. ### 3. Auto-Freeze is Enabled by Default
  263. DotLottie automatically freezes animations when they're not visible (offscreen). To disable this behavior:
  264. ```typescript
  265. const dotLottie = new DotLottie({
  266. canvas,
  267. src: 'animation.lottie',
  268. renderConfig: {
  269. freezeOnOffscreen: false, // Disable auto-freeze (not recommended)
  270. },
  271. });
  272. ```
  273. ### 4. Device Pixel Ratio
  274. By default, devicePixelRatio is set to 75% of the actual value for better performance. For full retina quality (with higher performance cost):
  275. ```typescript
  276. const dotLottie = new DotLottie({
  277. canvas,
  278. src: 'animation.lottie',
  279. renderConfig: {
  280. devicePixelRatio: window.devicePixelRatio, // Full retina (higher CPU/GPU)
  281. },
  282. });
  283. ```
  284. ### 5. Clean Up (Vanilla JS only)
  285. ```typescript
  286. // Always destroy when done (vanilla JS)
  287. dotLottie.destroy();
  288. ```
  289. **Note:** `DotLottieReact` handles cleanup automatically on unmount - no manual cleanup needed.
  290. ### 6. Frame Interpolation Control
  291. ```typescript
  292. const dotLottie = new DotLottie({
  293. canvas,
  294. src: 'animation.lottie',
  295. useFrameInterpolation: true, // Smooth playback (default)
  296. // useFrameInterpolation: false, // Match original AE frame rate
  297. });
  298. ```
  299. ## Multi-Animation Files
  300. A single `.lottie` file can contain multiple animations:
  301. ```typescript
  302. // Load specific animation by ID
  303. dotLottie.loadAnimation('animation-2');
  304. // Get all animation IDs
  305. const animations = dotLottie.manifest?.animations;
  306. // Returns: [{ id: 'animation-1' }, { id: 'animation-2' }]
  307. ```
  308. ## Canvas Sizing
  309. **Set canvas size via CSS styles** (recommended). DotLottie will automatically determine the optimal drawing area:
  310. ```html
  311. <canvas id="canvas" style="width: 400px; height: 400px;"></canvas>
  312. ```
  313. ### Auto-Resize to Container
  314. Use the `autoResize` render config to automatically resize when the container changes:
  315. ```typescript
  316. const dotLottie = new DotLottie({
  317. canvas,
  318. src: 'animation.lottie',
  319. renderConfig: {
  320. autoResize: true, // Canvas resizes to fit container
  321. },
  322. });
  323. ```
  324. ## Common Patterns
  325. ### Play on Hover
  326. ```typescript
  327. canvas.addEventListener('mouseenter', () => dotLottie.play());
  328. canvas.addEventListener('mouseleave', () => dotLottie.pause());
  329. ```
  330. ### Play on Click (Once)
  331. ```typescript
  332. canvas.addEventListener('click', () => {
  333. dotLottie.setFrame(0);
  334. dotLottie.setLoop(false);
  335. dotLottie.play();
  336. });
  337. ```
  338. ### Scrub with Scroll
  339. ```typescript
  340. window.addEventListener('scroll', () => {
  341. const progress = window.scrollY / (document.body.scrollHeight - window.innerHeight);
  342. const frame = progress * dotLottie.totalFrames;
  343. dotLottie.setFrame(frame);
  344. });
  345. ```
  346. ### Loading States (React)
  347. ```tsx
  348. function Animation() {
  349. const [isLoaded, setIsLoaded] = useState(false);
  350. return (
  351. <>
  352. {!isLoaded && <Skeleton />}
  353. <DotLottieReact
  354. src="animation.lottie"
  355. style={{ opacity: isLoaded ? 1 : 0 }}
  356. dotLottieRefCallback={(dotLottie) => {
  357. dotLottie.addEventListener('load', () => setIsLoaded(true));
  358. }}
  359. />
  360. </>
  361. );
  362. }
  363. ```
  364. ### Responsive Animation
  365. ```tsx
  366. function ResponsiveAnimation() {
  367. return (
  368. <DotLottieReact
  369. src="animation.lottie"
  370. autoplay
  371. loop
  372. style={{ width: '100%', maxWidth: '400px' }}
  373. renderConfig={{ autoResize: true }}
  374. />
  375. );
  376. }
  377. ```
  378. ## Debugging
  379. ```typescript
  380. // Check if loaded
  381. console.log('Loaded:', dotLottie.isLoaded);
  382. // Get animation info
  383. console.log('Duration:', dotLottie.duration);
  384. console.log('Total Frames:', dotLottie.totalFrames);
  385. console.log('Current Frame:', dotLottie.currentFrame);
  386. console.log('Is Playing:', dotLottie.isPlaying);
  387. console.log('Loop:', dotLottie.loop);
  388. console.log('Speed:', dotLottie.speed);
  389. // Get manifest (for .lottie files)
  390. console.log('Manifest:', dotLottie.manifest);
  391. ```
  392. ## Error Handling
  393. ```typescript
  394. dotLottie.addEventListener('loadError', (error) => {
  395. console.error('Failed to load animation:', error);
  396. // Show fallback UI
  397. });
  398. ```
  399. ## SSR / Next.js Considerations
  400. dotLottie requires browser APIs. For SSR frameworks:
  401. ```tsx
  402. import dynamic from 'next/dynamic';
  403. const DotLottieReact = dynamic(
  404. () => import('@lottiefiles/dotlottie-react').then(mod => mod.DotLottieReact),
  405. { ssr: false }
  406. );
  407. function Animation() {
  408. return <DotLottieReact src="animation.lottie" autoplay loop />;
  409. }
  410. ```
  411. ## Resources
  412. * Documentation: [https://developers.lottiefiles.com/docs/dotlottie-player](https://developers.lottiefiles.com/docs/dotlottie-player)
  413. * 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)
  414. * GitHub: [https://github.com/LottieFiles/dotlottie-web](https://github.com/LottieFiles/dotlottie-web)
  415. * dotLottie 2.0 Spec: [https://dotlottie.io/spec/2.0/](https://dotlottie.io/spec/2.0/)
  416. * 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.

  1. ![npm](https://img.shields.io/npm/v/@lottiefiles/dotlottie-web?label=%40lottiefiles%2Fdotlottie-web)
  2. ![npm bundle size](https://img.shields.io/bundlephobia/minzip/@lottiefiles/dotlottie-web)
  3. ![npm downloads](https://img.shields.io/npm/dw/@lottiefiles/dotlottie-web)
  4. ![jsDelivr hits](https://img.shields.io/jsdelivr/npm/hw/%40lottiefiles/dotlottie-web)
  5. ![GitHub](https://img.shields.io/github/license/LottieFiles/dotlottie-web)
  6. <p align="center">
  7. <img src="https://lottie.host/43f43646-b018-4d72-a96b-02a929cd9727/gARxdIetbE.svg" alt="dotLottie Web" width="550" />
  8. </p>
  9. <h1 align="center">dotLottie Web</h1>
  10. <p align="center">
  11. The official LottieFiles player for <b>Lottie</b> (<code>.json</code>) and
  12. <b>dotLottie</b> (<code>.lottie</code>) animations on the web — a Rust + WASM core
  13. powered by <a href="https://github.com/thorvg/thorvg">ThorVG</a>, with Software,
  14. WebGL2, and WebGPU rendering backends and full
  15. <a href="https://lottiefiles.com/dotlottie">dotLottie v2</a> support (theming, state machines,
  16. and audio).
  17. </p>
  18. <p align="center">
  19. <a href="https://lottiefiles.github.io/dotlottie-web/"><b>🌐 Live Viewer</b></a> ·
  20. <a href="https://lottiefiles.github.io/dotlottie-web/perf-test"><b>📊 Perf Playground</b></a> ·
  21. <a href="https://developers.lottiefiles.com/docs/dotlottie-player/dotlottie-web/"><b>📚 Docs</b></a> ·
  22. <a href="https://github.com/LottieFiles/dotlottie-rs"><b>🦀 dotLottie-rs</b></a>
  23. </p>
  24. # Why dotLottie Web
  25. * 📦 **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.
  26. * 🦀 **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.
  27. * 🎨 **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).
  28. * ⚡ **Three rendering backends** — Software (Canvas2D), WebGL2, and WebGPU (experimental). Switch with a one-line import change — same `DotLottie` class everywhere.
  29. * 📁 **dotLottie v2 ready** — first-class **theming**, interactive **state machines**, and **audio** in a single `.lottie` file. No userland wiring required.
  30. * 🧵 **Off-main-thread** — `DotLottieWorker` renders on a Web Worker with `OffscreenCanvas`, keeping your UI buttery-smooth even with dozens of animations.
  31. * ⚛️ **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.
  32. * 🎛️ **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.
  33. ## Quick Start
  34. 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:
  35. ### Vanilla JS
  36. ```bash
  37. npm install @lottiefiles/dotlottie-web
  38. ```
  39. ```html
  40. <canvas id="canvas" style="width: 300px; height: 300px"></canvas>
  41. ```
  42. ```js
  43. import { DotLottie } from '@lottiefiles/dotlottie-web';
  44. const dotLottie = new DotLottie({
  45. canvas: document.getElementById('canvas'),
  46. src: 'https://your-animation-url.lottie',
  47. autoplay: true,
  48. loop: true,
  49. });
  50. ```
  51. <details>
  52. <summary><b>⚛️ React</b></summary>
  53. ```bash
  54. npm install @lottiefiles/dotlottie-react
  55. ```
  56. ```jsx
  57. import { DotLottieReact } from '@lottiefiles/dotlottie-react';
  58. const App = () => (
  59. <DotLottieReact
  60. src="path/to/animation.lottie"
  61. loop
  62. autoplay
  63. />
  64. );
  65. ```
  66. </details>
  67. <details>
  68. <summary><b>💚 Vue</b></summary>
  69. ```bash
  70. npm install @lottiefiles/dotlottie-vue
  71. ```
  72. ```vue
  73. <script setup>
  74. import { DotLottieVue } from '@lottiefiles/dotlottie-vue';
  75. </script>
  76. <template>
  77. <DotLottieVue
  78. style="height: 500px; width: 500px"
  79. autoplay
  80. loop
  81. src="https://path-to-lottie.lottie"
  82. />
  83. </template>
  84. ```
  85. </details>
  86. <details>
  87. <summary><b>🧡 Svelte</b></summary>
  88. ```bash
  89. npm install @lottiefiles/dotlottie-svelte
  90. ```
  91. ```svelte
  92. <script lang="ts">
  93. import { DotLottieSvelte } from '@lottiefiles/dotlottie-svelte';
  94. </script>
  95. <DotLottieSvelte src="path/to/animation.lottie" loop autoplay />
  96. ```
  97. </details>
  98. <details>
  99. <summary><b>🔵 Solid</b></summary>
  100. ```bash
  101. npm install @lottiefiles/dotlottie-solid
  102. ```
  103. ```jsx
  104. import { DotLottieSolid } from '@lottiefiles/dotlottie-solid';
  105. const App = () => (
  106. <DotLottieSolid
  107. src="path/to/animation.lottie"
  108. loop
  109. autoplay
  110. />
  111. );
  112. ```
  113. </details>
  114. <details>
  115. <summary><b>🌐 Web Component (drop-in, no build step)</b></summary>
  116. ```html
  117. <dotlottie-wc
  118. src="https://lottie.host/4db68bbd-31f6-4cd8-84eb-189de081159a/IGmMCqhzpt.lottie"
  119. autoplay
  120. loop
  121. ></dotlottie-wc>
  122. <script
  123. type="module"
  124. src="https://unpkg.com/@lottiefiles/dotlottie-wc@latest/dist/dotlottie-wc.js"
  125. ></script>
  126. ```
  127. Or via npm:
  128. ```bash
  129. npm install @lottiefiles/dotlottie-wc
  130. ```
  131. ```js
  132. import '@lottiefiles/dotlottie-wc';
  133. ```
  134. </details>
  135. ## Features
  136. ### 🤖 Interactive State Machines
  137. 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.
  138. ```js
  139. const dotLottie = new DotLottie({
  140. canvas: document.getElementById('canvas'),
  141. src: 'interactive-button.lottie',
  142. stateMachineId: 'main',
  143. autoplay: true,
  144. });
  145. ```
  146. The player exposes typed events for `stateMachineStart`, `stateMachineTransition`, `stateMachineStateEntered`, custom events, and input changes — perfect for wiring animations into your UI logic.
  147. ### 🎨 Runtime Theming
  148. 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.
  149. ```js
  150. // Use a theme defined in the .lottie manifest
  151. dotLottie.setTheme('dark');
  152. // Or supply a theme object at runtime
  153. dotLottie.setThemeData({
  154. rules: [
  155. { id: 'primary', type: 'Color', value: [0.9, 0.2, 0.4, 1.0] },
  156. ],
  157. });
  158. ```
  159. The full `Theme` type covers color, scalar, position, vector, gradient, image, and text rules — all keyframe-aware.
  160. ### 🔊 Audio Support
  161. `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.
  162. > Audio is an experimental feature in `dotlottie-rs`. Browser autoplay policies still apply — initiate playback from a user gesture.
  163. ### 🧵 Off-Main-Thread Rendering
  164. 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.
  165. ```js
  166. import { DotLottieWorker } from '@lottiefiles/dotlottie-web';
  167. const player = new DotLottieWorker({
  168. canvas: document.getElementById('canvas'),
  169. src: 'animation.lottie',
  170. autoplay: true,
  171. loop: true,
  172. workerId: 'shared-pool', // optional: share one worker across many instances
  173. });
  174. ```
  175. All `DotLottieWorker` methods are async (Promise-returning) since they cross a worker boundary.
  176. ### ⚡ Hardware-Accelerated Rendering
  177. The default Software backend works everywhere. For demanding workloads — many concurrent animations, large canvases, complex masks — opt in to GPU rendering via subpath imports:
  178. ```js
  179. // WebGL2 — broadly supported
  180. import { DotLottie } from '@lottiefiles/dotlottie-web/webgl';
  181. // WebGPU — experimental, modern Chromium / Safari TP
  182. import { DotLottie } from '@lottiefiles/dotlottie-web/webgpu';
  183. ```
  184. 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).
  185. > 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.
  186. ### 🖼️ More built-in capabilities
  187. * **Multi-animation `.lottie` files** — `animationId` config + `loadAnimation(id)` to switch between bundled animations
  188. * **Named markers** — `setMarker(name)` and `markers()` to play AE-defined segments
  189. * **Frame segments** — `setSegment(start, end)` for arbitrary frame ranges
  190. * **Layout** — `fit` (`contain` / `cover` / `fill` / `fit-width` / `fit-height` / `none`) + normalized `align: [x, y]`
  191. * **Slots** — bind dynamic data to color, scalar, vector, gradient, text, and image slots at runtime
  192. * **Playback modes** — `forward` / `reverse` / `bounce` / `reverse-bounce` with configurable loop counts
  193. * **Frame interpolation** — smooth subframe playback (default on) or pinned to the original AE frame rate
  194. * **Freeze on offscreen** — automatically pause rendering when the canvas leaves the viewport
  195. * **25+ typed events** — `play`, `pause`, `frame`, `complete`, `loop`, `load`, `loadError`, `freeze`, plus the full state-machine event suite
  196. ## Packages
  197. All packages render both Lottie (`.json`) and dotLottie (`.lottie`) animations.
  198. | Package | Description |
  199. | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
  200. | **[@lottiefiles/dotlottie-web](packages/web/README.md)** | Core Lottie & dotLottie player — Rust/WASM via dotlottie-rs, Canvas2D / WebGL / WebGPU, Node-isomorphic |
  201. | **[@lottiefiles/dotlottie-react](packages/react/README.md)** | React component for Lottie & dotLottie |
  202. | **[@lottiefiles/dotlottie-vue](packages/vue/README.md)** | Vue 3 component for Lottie & dotLottie |
  203. | **[@lottiefiles/dotlottie-svelte](packages/svelte/README.md)** | Svelte component for Lottie & dotLottie |
  204. | **[@lottiefiles/dotlottie-solid](packages/solid/README.md)** | Solid component for Lottie & dotLottie |
  205. | **[@lottiefiles/dotlottie-wc](packages/wc/README.md)** | Framework-agnostic Web Component for Lottie & dotLottie |
  206. Each package README contains its full API reference, prop tables, and event documentation.
  207. ## dotLottie Viewer
  208. A hosted companion app at **[lottiefiles.github.io/dotlottie-web](https://lottiefiles.github.io/dotlottie-web/)** for inspecting, debugging, and benchmarking animations:
  209. | Page | What it does |
  210. | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  211. | [**Home**](https://lottiefiles.github.io/dotlottie-web/) | Drop a `.lottie` or `.json` file to preview rendering and inspect manifest details |
  212. | [**Playground**](https://lottiefiles.github.io/dotlottie-web/playground) | Interactive editor for player config, themes, markers, and animation switching |
  213. | [**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 |
  214. | [**List**](https://lottiefiles.github.io/dotlottie-web/list) | Gallery of curated animations |
  215. | [**Embed**](https://lottiefiles.github.io/dotlottie-web/embed) | Embedding patterns and demos |
  216. Source: [`apps/viewer/`](apps/viewer/).
  217. ## Live Examples (CodePen)
  218. **[@lottiefiles/dotlottie-web](packages/web/README.md)** —
  219. [Getting Started](https://codepen.io/lottiefiles/pen/JjzJZmL) ·
  220. [Playback Controls](https://codepen.io/lottiefiles/pen/dyrRKwg) ·
  221. [Dynamic Loading](https://codepen.io/lottiefiles/pen/JjzJZgB) ·
  222. [Worker](https://codepen.io/lottiefiles/pen/VwJZPrQ) ·
  223. [Multi Animations](https://codepen.io/lottiefiles/pen/wvOxdRa) ·
  224. [Advanced Layout](https://codepen.io/lottiefiles/pen/LYvZveR) ·
  225. [Named Markers](https://codepen.io/lottiefiles/pen/RwOROKp) ·
  226. [Theming](https://codepen.io/lottiefiles/pen/BaEzEeq) ·
  227. [Interactivity](https://codepen.io/lottiefiles/pen/VwJvdRN)
  228. **[@lottiefiles/dotlottie-react](packages/react/README.md)** —
  229. [Getting Started](https://codepen.io/lottiefiles/pen/vYPJpBN) ·
  230. [Custom Controls](https://codepen.io/lottiefiles/pen/WNmEdxd)
  231. **[@lottiefiles/dotlottie-vue](packages/vue/README.md)** —
  232. [Getting Started](https://codepen.io/lottiefiles/pen/yLwgeoJ)
  233. ## Local Examples
  234. Runnable example apps in [`examples/`](examples/):
  235. | Example | Package | Highlights |
  236. | ------------------------------ | ---------------------------------------- | --------------------------------------------- |
  237. | [web](examples/web/) | `@lottiefiles/dotlottie-web` | State machines, themes, segments, layout |
  238. | [web-node](examples/web-node/) | `@lottiefiles/dotlottie-web` (Node.js) | Server-side rendering to a buffer |
  239. | [react](examples/react/) | `@lottiefiles/dotlottie-react` | Renderer selection (canvas/webgl/webgpu) |
  240. | [vue](examples/vue/) | `@lottiefiles/dotlottie-vue` | Theme toggling, ref/event patterns |
  241. | [solid](examples/solid/) | `@lottiefiles/dotlottie-solid` | Signal-based state, theme/animation switching |
  242. | [wc](examples/wc/) | `@lottiefiles/dotlottie-wc` | Web Component usage and event delegation |
  243. | [next](examples/next/) | `@lottiefiles/dotlottie-react` (Next.js) | SSR-safe rendering with the App Router |
  244. ```bash
  245. pnpm install && pnpm run build
  246. cd examples/web
  247. pnpm run dev
  248. ```
  249. ## Browser & Runtime Support
  250. **Required:** WebAssembly · Canvas 2D · Fetch API
  251. **Optional (enhances perf):** Web Workers · OffscreenCanvas · WebGL2 (for `/webgl`) · WebGPU (for `/webgpu`)
  252. | Browser | Minimum version |
  253. | ---------- | --------------- |
  254. | Chrome | 57+ (Mar 2017) |
  255. | Firefox | 52+ (Mar 2017) |
  256. | Safari | 11+ (Sep 2017) |
  257. | Edge | 16+ (Oct 2017) |
  258. | iOS Safari | 11+ (Sep 2017) |
  259. **Node.js:** 18+ — `@lottiefiles/dotlottie-web` is isomorphic and runs server-side for thumbnail generation, frame extraction, or static rendering.
  260. ## Development
  261. **Prerequisites:** Node.js 22+, pnpm 10+
  262. ```bash
  263. git clone https://github.com/LottieFiles/dotlottie-web.git
  264. cd dotlottie-web
  265. pnpm install
  266. pnpm run build # Build all packages
  267. pnpm run dev # Watch mode
  268. pnpm run test # Run tests
  269. pnpm run lint # Lint
  270. pnpm run format # Format
  271. ```
  272. ## Contributing
  273. Contributions are welcome! Read the [Contributing Guidelines](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) before opening an issue or PR.
  274. ## License
  275. [MIT](LICENSE) © [LottieFiles](https://www.lottiefiles.com)
scripts/dev-release-report.mjs · Bundled script · 158 lines · 1 finding marked
  1. // Reports a published dev snapshot: writes the job summary and upserts a sticky
  2. // comment on the branch's open PR. Run after `changeset publish` in release.yml.
  3. //
  4. // Usage:
  5. // node scripts/dev-release-report.mjs
  6. // node scripts/dev-release-report.mjs --dry-run # print the comment, call no APIs
  7. import fs from 'node:fs/promises';
  8. import path from 'node:path';
  9. import { fileURLToPath } from 'node:url';
  10. const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
  11. const MARKER = '<!-- dev-release-snapshot -->';
  12. const BOT = 'github-actions[bot]';
  13. const dryRun = process.argv.includes('--dry-run');
  14. const {
  15. GITHUB_TOKEN,
  16. GITHUB_REPOSITORY,
  17. GITHUB_REF_NAME,
  18. GITHUB_SHA,
  19. GITHUB_RUN_ID,
  20. GITHUB_SERVER_URL = 'https://github.com',
  21. GITHUB_STEP_SUMMARY,
  22. } = process.env;
  23. /** Every publishable package in the workspace, so a new package is never silently skipped. */
  24. async function publishedPackages() {
  25. const dirs = await fs.readdir(path.join(ROOT, 'packages'));
  26. const pkgs = await Promise.all(
  27. dirs.map(async (dir) => {
  28. const manifest = path.join(ROOT, 'packages', dir, 'package.json');
  29. const pkg = JSON.parse(await fs.readFile(manifest, 'utf-8'));
  30. return pkg.private ? null : pkg;
  31. }),
  32. );
  33. return pkgs.filter(Boolean).sort((a, b) => a.name.localeCompare(b.name));
  34. }
  35. function renderComment(packages, version) {
  36. // The web package is what people actually install; the rest go in a fold.
  37. const primary = packages.find((pkg) => pkg.name.endsWith('/dotlottie-web')) ?? packages[0];
  38. const rest = packages.filter((pkg) => pkg !== primary);
  39. const lines = [
  40. MARKER,
  41. '### 🚀 Dev release published',
  42. '',
  43. `All packages published at \`${version}\` under the \`dev\` dist-tag.`,
  44. '',
  45. '```sh',
  46. `npm i ${primary.name}@${version}`,
  47. '```',
  48. '',
  49. ];
  50. if (rest.length > 0) {
  51. lines.push(
  52. '<details><summary>Other packages</summary>',
  53. '',
  54. '```sh',
  55. ...rest.map((pkg) => `npm i ${pkg.name}@${version}`),
  56. '```',
  57. '',
  58. '</details>',
  59. '',
  60. );
  61. }
  62. const runUrl = `${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}`;
  63. lines.push(
  64. 'Published to both npmjs and GitHub Packages, so it resolves regardless of which',
  65. '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
  66. '',
  67. `Built from \`${GITHUB_REF_NAME}\` @ \`${GITHUB_SHA}\` · [run](${runUrl})`,
  68. );
  69. return lines.join('\n');
  70. }
  71. async function api(endpoint, options = {}) {
  72. const response = await fetch(`https://api.github.com${endpoint}`, {
  73. ...options,
  74. headers: {
  75. accept: 'application/vnd.github+json',
  76. authorization: `Bearer ${GITHUB_TOKEN}`,
  77. 'x-github-api-version': '2022-11-28',
  78. ...options.headers,
  79. },
  80. });
  81. if (!response.ok) {
  82. throw new Error(
  83. `GitHub API ${options.method ?? 'GET'} ${endpoint} failed: ${response.status} ${await response.text()}`,
  84. );
  85. }
  86. return response.json();
  87. }
  88. /** The open PR for this branch, or null when the release was cut from a bare branch. */
  89. async function findOpenPullRequest() {
  90. const [owner] = GITHUB_REPOSITORY.split('/');
  91. const query = new URLSearchParams({ head: `${owner}:${GITHUB_REF_NAME}`, state: 'open' });
  92. const [pr] = await api(`/repos/${GITHUB_REPOSITORY}/pulls?${query}`);
  93. return pr ?? null;
  94. }
  95. /**
  96. * Our own previous report, if any. Matching on the marker alone is not enough:
  97. * anyone quoting the comment copies the marker with it, and we must not edit
  98. * a human's comment.
  99. */
  100. async function findPreviousComment(prNumber) {
  101. const comments = await api(`/repos/${GITHUB_REPOSITORY}/issues/${prNumber}/comments?per_page=100`);
  102. return comments.find((comment) => comment.user.login === BOT && comment.body.startsWith(MARKER)) ?? null;
  103. }
  104. const packages = await publishedPackages();
  105. const { version } = packages.find((pkg) => pkg.name.endsWith('/dotlottie-web')) ?? packages[0];
  106. const body = renderComment(packages, version);
  107. if (dryRun) {
  108. console.log(body);
  109. process.exit(0);
  110. }
  111. if (GITHUB_STEP_SUMMARY) await fs.appendFile(GITHUB_STEP_SUMMARY, `${body}\n`);
  112. const pr = await findOpenPullRequest();
  113. if (!pr) {
  114. console.log(`Published ${version}, but '${GITHUB_REF_NAME}' has no open PR — nothing to comment on.`);
  115. process.exit(0);
  116. }
  117. const previous = await findPreviousComment(pr.number);
  118. // Upsert, so repeated dev releases on one PR don't pile up comments.
  119. if (previous) {
  120. await api(`/repos/${GITHUB_REPOSITORY}/issues/comments/${previous.id}`, {
  121. method: 'PATCH',
  122. body: JSON.stringify({ body }),
  123. });
  124. console.log(`Updated comment ${previous.id} on PR #${pr.number} with ${version}`);
  125. } else {
  126. await api(`/repos/${GITHUB_REPOSITORY}/issues/${pr.number}/comments`, {
  127. method: 'POST',
  128. body: JSON.stringify({ body }),
  129. });
  130. console.log(`Commented on PR #${pr.number} with ${version}`);
  131. }

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.