Lottie for Web

Common errors

• TypeError: lottie.loadAnimation is not a function

  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.
  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.

• Cannot read properties of undefined (reading 'play') / TypeError: anim.play is not a function

  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.
  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.

• Animation not visible or not playing after loading.

  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).
  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.

• Images or other assets within the Lottie animation are not loading or appearing.

  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.
  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.

Warnings

• breaking 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.
  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')`).
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• deprecated 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.
  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.

Install

• npm install lottie-web npm
• yarn add lottie-web yarn
• pnpm add lottie-web pnpm

Imports

• lottie
  wrong:

  const lottie = require('lottie-web');

  correct:

  import lottie from 'lottie-web';

  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.
• lottie.loadAnimation
  wrong:

  lottie.loadAnimation(document.getElementById('anim'), { path: '/data.json' });

  correct:

  lottie.loadAnimation({ container: document.getElementById('anim'), path: '/data.json' });

  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.
• AnimationItem (instance)
  wrong:

  lottie.play('myAnim'); lottie.destroy('myAnim');

  correct:

  const anim = lottie.loadAnimation(...); anim.play(); anim.destroy();

  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`.

Quickstart

This quickstart demonstrates how to import `lottie-web`, initialize an animation using inline JSON data, and attach basic play/pause controls on mouse events.

import lottie from 'lottie-web';

const animationData = {
  v: '5.10.0',
  fr: 60,
  ip: 0,
  op: 180,
  w: 500,
  h: 500,
  nm: 'Simple Animation',
  ddd: 0,
  assets: [],
  layers: [
    {
      ddd: 0,
      ind: 1,
      ty: 4,
      nm: 'Square',
      sr: 1,
      ks: {
        o: { a: 0, k: 100, ix: 11 },
        r: { a: 0, k: 0, ix: 10 },
        p: { a: 1, k: [{t:0, s:[250,250,0]}, {t:90, s:[100,250,0]}, {t:180, s:[250,250,0]}], ix: 2},
        a: { a: 0, k: [25, 25, 0], ix: 1},
        s: { a: 0, k: [100, 100, 100], ix: 6}
      },
      ao: 0,
      shapes: [
        {
          ty: 'gr',
          it: [
            { 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},
            { 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}},
            { 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}
          ],
          nm: 'Group 1', mn: 'ADBE Vector Group', hd: false
        }
      ],
      ip: 0, op: 180, st: 0, bm: 0
    }
  ],
  markers: []
};

function initLottieAnimation() {
  const container = document.getElementById('lottie-container');
  if (!container) {
    console.error('Lottie container not found!');
    return;
  }

  const anim = lottie.loadAnimation({
    container: container,
    renderer: 'svg', // Can be 'svg', 'canvas', or 'html'
    loop: true,
    autoplay: true,
    animationData: animationData // Or use 'path: "/path/to/animation.json"'
  });

  // Optional: Control animation playback
  container.addEventListener('mouseenter', () => anim.pause());
  container.addEventListener('mouseleave', () => anim.play());
}

document.addEventListener('DOMContentLoaded', initLottieAnimation);

// To make it runnable in a browser, you'd typically have this in an HTML file:
/*
<div id="lottie-container" style="width: 300px; height: 300px; background-color: #f0f0f0; border: 1px solid #ccc;"></div>
<script type="module" src="./main.js"></script>
*/