{"id":11255,"library":"lottie-web","title":"Lottie for Web","description":"Lottie-web is a JavaScript library designed to render animations exported from Adobe After Effects as JSON files, leveraging the Bodymovin plugin. It enables designers to deliver complex, vector-based animations across web platforms without the need for manual re-coding by engineers, significantly streamlining the animation pipeline. The package, as of the provided context, is at version 5.13.0, which includes critical bug fixes and improvements, notably around Node.js compatibility for SSR. Lottie-web is actively maintained, with new features and bug fixes released periodically, though major versions with breaking changes (like the recent v6) are less frequent. Key differentiators include its tight integration with After Effects, robust performance across SVG and Canvas renderers, and a comprehensive API for controlling animation playback, speed, and segments. It is a core component of the broader Lottie ecosystem, alongside its counterparts for Android, iOS, and React Native, providing a unified animation solution.","status":"active","version":"5.13.0","language":"javascript","source_language":"en","source_url":"https://github.com/airbnb/lottie-web","tags":["javascript","animation","canvas","svg","after effects","plugin","export","typescript"],"install":[{"cmd":"npm install lottie-web","lang":"bash","label":"npm"},{"cmd":"yarn add lottie-web","lang":"bash","label":"yarn"},{"cmd":"pnpm add lottie-web","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `lottie-web` package exports a default object, typically aliased as `lottie`. CommonJS `require` is also supported in versions up to 5.x. For v6+, direct CommonJS `require` of the main bundle might be affected due to UMD bundle removal.","wrong":"const lottie = require('lottie-web');","symbol":"lottie","correct":"import lottie from 'lottie-web';"},{"note":"In version 5.x, `loadAnimation` expects a single object as an argument. The signature changed significantly in v6, where `container` became the first positional argument.","wrong":"lottie.loadAnimation(document.getElementById('anim'), { path: '/data.json' });","symbol":"lottie.loadAnimation","correct":"lottie.loadAnimation({ container: document.getElementById('anim'), path: '/data.json' });"},{"note":"Global methods like `lottie.play()` or `lottie.destroy()` that operate on named animations were largely refactored in v6. Post-v6, control methods (play, pause, destroy, setSpeed, etc.) should be called directly on the animation instance returned by `lottie.loadAnimation`.","wrong":"lottie.play('myAnim'); lottie.destroy('myAnim');","symbol":"AnimationItem (instance)","correct":"const anim = lottie.loadAnimation(...); anim.play(); anim.destroy();"}],"quickstart":{"code":"import lottie from 'lottie-web';\n\nconst animationData = {\n  v: '5.10.0',\n  fr: 60,\n  ip: 0,\n  op: 180,\n  w: 500,\n  h: 500,\n  nm: 'Simple Animation',\n  ddd: 0,\n  assets: [],\n  layers: [\n    {\n      ddd: 0,\n      ind: 1,\n      ty: 4,\n      nm: 'Square',\n      sr: 1,\n      ks: {\n        o: { a: 0, k: 100, ix: 11 },\n        r: { a: 0, k: 0, ix: 10 },\n        p: { a: 1, k: [{t:0, s:[250,250,0]}, {t:90, s:[100,250,0]}, {t:180, s:[250,250,0]}], ix: 2},\n        a: { a: 0, k: [25, 25, 0], ix: 1},\n        s: { a: 0, k: [100, 100, 100], ix: 6}\n      },\n      ao: 0,\n      shapes: [\n        {\n          ty: 'gr',\n          it: [\n            { ind: 0, ty: 'sh', ix: 1, ks: { a: 0, k: { i: [[-25,-25],[25,-25],[-25,25],[25,25]], o: [[25,-25],[-25,-25],[25,25],[-25,25]], v: [[-25,25],[25,25],[25,-25],[-25,-25]] }, ix: 2},\n            { ind: 1, ty: 'fl', ix: 2, c: { a: 0, k: [0.7,0.2,0.1,1], ix: 3}, o: { a: 0, k: 100, ix: 4}},\n            { ind: 2, ty: 'st', ix: 3, c: { a: 0, k: [0,0,0,1], ix: 5}, o: { a: 0, k: 100, ix: 6}, w: { a: 0, k: 2, ix: 7}, lc: 1, lj: 1, ml: 4}\n          ],\n          nm: 'Group 1', mn: 'ADBE Vector Group', hd: false\n        }\n      ],\n      ip: 0, op: 180, st: 0, bm: 0\n    }\n  ],\n  markers: []\n};\n\nfunction initLottieAnimation() {\n  const container = document.getElementById('lottie-container');\n  if (!container) {\n    console.error('Lottie container not found!');\n    return;\n  }\n\n  const anim = lottie.loadAnimation({\n    container: container,\n    renderer: 'svg', // Can be 'svg', 'canvas', or 'html'\n    loop: true,\n    autoplay: true,\n    animationData: animationData // Or use 'path: \"/path/to/animation.json\"'\n  });\n\n  // Optional: Control animation playback\n  container.addEventListener('mouseenter', () => anim.pause());\n  container.addEventListener('mouseleave', () => anim.play());\n}\n\ndocument.addEventListener('DOMContentLoaded', initLottieAnimation);\n\n// To make it runnable in a browser, you'd typically have this in an HTML file:\n/*\n<div id=\"lottie-container\" style=\"width: 300px; height: 300px; background-color: #f0f0f0; border: 1px solid #ccc;\"></div>\n<script type=\"module\" src=\"./main.js\"></script>\n*/","lang":"typescript","description":"This quickstart demonstrates how to import `lottie-web`, initialize an animation using inline JSON data, and attach basic play/pause controls on mouse events."},"warnings":[{"fix":"Review the v6 changelog and migrate `loadAnimation` calls to the new signature. Update animation control calls to use the `AnimationItem` instance (e.g., `anim.destroy()` instead of `lottie.destroy('name')`).","message":"Lottie-web v6.0.0 introduced significant breaking changes. The `lottie.loadAnimation` signature changed from accepting an options object to positional arguments (e.g., `container` is now the first argument). Many global methods like `lottie.destroy()` or `lottie.setSpeed()` were removed, and their functionality moved to methods on the individual `AnimationItem` instances.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"For browser environments, consider using an ESM-compatible CDN or ensure your build process correctly bundles ESM or CJS versions. For Node.js (SSR), ensure your setup correctly handles ESM or CJS imports.","message":"Starting with v6.0.0, the UMD (Universal Module Definition) bundle was dropped. This means direct inclusion via a `<script>` tag might require different assets or build configurations. The library now primarily supports ES Modules and CommonJS.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Always call `animationInstance.destroy()` when the animation's container element is removed from the DOM or the animation is no longer required. For versions prior to v6, `lottie.destroy(animationName)` could also be used.","message":"Animations, especially those loaded dynamically or in single-page applications, can cause memory leaks if not properly destroyed when no longer needed. This can lead to performance degradation over time.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"Ensure `assetsPath` in `loadAnimation` points to the correct base directory for images, or verify that image paths within the JSON are correct relative to the HTML file or the animation loader's context.","message":"If your Lottie animation JSON includes external assets like images, their paths must be correctly configured using the `assetsPath` option in `loadAnimation` or by ensuring relative paths are accurate. Incorrect paths will result in missing images.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"Experiment with different renderers based on animation complexity and target device performance. SVG is often the default and a good starting point for vector animations.","message":"Choosing the correct renderer (`'svg'`, `'canvas'`, or `'html'`) is crucial for performance and fidelity. SVG offers vector scalability but can be heavy for complex animations with many layers. Canvas can be faster for raster-heavy or very complex animations but lacks the DOM manipulability of SVG. HTML renderer is less common but can be useful for certain effects.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"For new projects, evaluate `@lottiefiles/dotlottie-web` if `.lottie` format, WebAssembly, or Web Workers are priorities. Continue using `lottie-web` for existing projects or when direct JSON rendering is preferred.","message":"While still actively maintained by Airbnb, some community discussions suggest a potential shift or deprecation of `lottie-web` in favor of `@lottiefiles/dotlottie-web` for certain use cases, especially for `.lottie` file format support and WebAssembly/Web Worker benefits, though this is not an official Airbnb deprecation.","severity":"deprecated","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify the import statement (`import lottie from 'lottie-web';` or `const lottie = require('lottie-web');`). Ensure the correct version of `lottie-web` is installed for your code's API usage. If using a `<script>` tag, ensure it's loaded before your animation logic.","cause":"This error typically occurs if `lottie-web` was not imported correctly, or if a v6 API call is attempted in an environment where an older version (e.g., 5.x) is loaded, or vice-versa. It can also happen if attempting to call `loadAnimation` before the `lottie` object is fully available.","error":"TypeError: lottie.loadAnimation is not a function"},{"fix":"Always store the return value of `lottie.loadAnimation()` into a variable (e.g., `const anim = lottie.loadAnimation(...)`). Add checks (`if (anim) { anim.play(); }`) to ensure the instance exists before interacting with it. For v6, ensure you're calling `play()` on the instance, not the global `lottie` object.","cause":"This usually means the `animationInstance` (returned by `lottie.loadAnimation`) was not stored, or the animation failed to load, resulting in `undefined`. It can also occur if attempting to call global `lottie.play()` in v6.","error":"Cannot read properties of undefined (reading 'play') / TypeError: anim.play is not a function"},{"fix":"Double-check the `container` element's ID and existence, the `path` to your `.json` file, and ensure `autoplay` is `true` if immediate playback is desired. Verify the container has sufficient `width` and `height` and is visible in the DOM. Check browser console for network errors loading the JSON.","cause":"Common causes include an incorrect `container` DOM element reference, an invalid or unreachable `path` to the animation JSON, `autoplay` being set to `false`, or issues with CSS on the container element (e.g., `display: none`, zero height/width).","error":"Animation not visible or not playing after loading."},{"fix":"Ensure that the `assetsPath` option in `lottie.loadAnimation` correctly points to the directory containing your animation's images. If no `assetsPath` is specified, images are expected to be relative to the animation JSON file or the page's base URL.","cause":"This indicates that `lottie-web` cannot find the associated image files referenced in the animation JSON. This is usually due to incorrect `assetsPath` configuration or incorrect relative paths in the JSON itself.","error":"Images or other assets within the Lottie animation are not loading or appearing."}],"ecosystem":"npm"}