react-lottie 2.3.0 → 2.3.2

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [2.3.2](https://github.com/chenqingspring/react-lottie/compare/v2.3.1...v2.3.2) (2026-11-07)
+
+### Bug Fixes
+
+* accept a namespace import (`import * as animationData`) by unwrapping its `default` export and clone frozen animation objects before handing them to lottie-web, so they no longer fail with `Cannot read property 'length' of undefined` (#24, #65)
+* throw an actionable error when `options.animationData` is a string or when neither `animationData` nor `path` is provided, instead of lottie-web's `Cannot create property 'tf' on string` / `Cannot read property 'length' of undefined` deep in the renderer (#44)
+* fix the README examples that read `.default` from a default import, which passed `undefined` as the animation data
+
+## [2.3.1](https://github.com/chenqingspring/react-lottie/compare/v2.3.0...v2.3.1) (2026-11-05)
+
+### Bug Fixes
+
+* tolerate a missing or non-array `eventListeners` prop instead of throwing `eventListeners.forEach is not a function` on mount and unmount, which could break animations rendered through `React.lazy` ([#137](https://github.com/chenqingspring/react-lottie/issues/137))
+
 ## [2.3.0](https://github.com/chenqingspring/react-lottie/compare/v2.2.0...v2.3.0) (2026-11-05)
 
 ### Features

package/README.md

@@ -37,6 +37,70 @@ npm install --save react-lottie
 > [GitHub](https://github.com/chenqingspring/react-lottie/issues) and Relay
 > will review and fix it.
 
+## Using from a CDN (no bundler)
+
+The published `dist/index.js` is a CommonJS build for bundlers and npm
+consumers. It uses `exports` and expects `react`, `prop-types` and `lottie-web`
+to be resolvable, so loading that file with a plain `<script>` tag fails with
+`Uncaught ReferenceError: exports is not defined`. The package does not ship a
+UMD/browser global build.
+
+To use react-lottie without a build step, load it as an ES module from a CDN
+and map `react` to the same copy the page uses. [esm.sh](https://esm.sh)
+supports `?external=react` for exactly this:
+
+```html
+<script type="importmap">
+  {
+    "imports": {
+      "react": "https://esm.sh/react@18",
+      "react-dom/client": "https://esm.sh/react-dom@18/client",
+      "react-lottie": "https://esm.sh/react-lottie@2?external=react"
+    }
+  }
+</script>
+<script type="module">
+  import React from 'react';
+  import { createRoot } from 'react-dom/client';
+  import Lottie from 'react-lottie';
+
+  const options = {
+    path: '/animations/pinjump.json',
+    loop: true,
+    autoplay: true,
+  };
+
+  createRoot(document.getElementById('root')).render(
+    React.createElement(Lottie, { options, height: 400, width: 400 })
+  );
+</script>
+```
+
+Without a compiler for JSX, create elements with `React.createElement`, or add
+`htm`/Babel. Keeping `react` in the import map gives the page one React
+instance; a CDN build that bundles its own React (such as jsDelivr's `+esm`
+output) produces two copies, which breaks context and hooks.
+
+If you only need to play an animation and not the React wrapper, load
+lottie-web directly and skip React entirely:
+
+```html
+<script src="https://cdnjs.cloudflare.com/ajax/libs/bodymovin/5.12.2/lottie.min.js"></script>
+<script>
+  lottie.loadAnimation({
+    container: document.getElementById('root'),
+    path: '/animations/pinjump.json',
+    renderer: 'svg',
+    loop: true,
+    autoplay: true,
+  });
+</script>
+```
+
+An ESM CDN build still downloads React, React DOM, lottie-web and react-lottie,
+so it removes the build step but not the bytes. For production, a bundler that
+shares one React copy and tree-shakes lottie-web is smaller.
+
 ## Requirements
 
 React 16.8 or newer. The test suite runs against React 18; the component uses
@@ -95,7 +159,7 @@ export default class LottieControl extends React.Component {
     const defaultOptions = {
       loop: true,
       autoplay: true, 
-      animationData: animationData.default,
+      animationData,
       rendererSettings: {
         preserveAspectRatio: 'xMidYMid slice'
       }
@@ -116,6 +180,11 @@ export default class LottieControl extends React.Component {
 
 ```
 
+Pass the parsed animation object as `options.animationData`. A file path or URL
+belongs in `options.path`; a namespace import
+(`import * as animationData`) is unwrapped automatically but the default import
+above is preferred.
+
 ### Loading animation data without bloating the bundle
 
 A static import like `import animationData from './pinjump.json'` (the example
@@ -211,7 +280,7 @@ export default class HoverLottie extends React.Component {
     const defaultOptions = {
       loop: false,
       autoplay: false,
-      animationData: animationData.default,
+      animationData,
       rendererSettings: {
         preserveAspectRatio: 'xMidYMid slice'
       }

package/dist/index.js

@@ -32,6 +32,35 @@ var segmentsAreEqual = function segmentsAreEqual(a, b) {
     return value === b[index];
   });
 };
+
+/* lottie-web crashes deep inside its renderer with "Cannot read property
+   'length' of undefined" when the data is not a plain animation object. Accept
+   the shapes users actually pass (a namespace import, a frozen ESM object) and
+   fail with an actionable message for the rest (#24, #44, #65). */
+var _normalizeAnimationData = function normalizeAnimationData(animationData, path) {
+  if (animationData === undefined || animationData === null) {
+    if (!path) {
+      throw new Error('[react-lottie] options must include `animationData` (the imported JSON) ' + 'or `path` (a URL to the JSON file).');
+    }
+    return animationData;
+  }
+  if (typeof animationData === 'string') {
+    throw new Error('[react-lottie] options.animationData must be an object, not a string. ' + 'Pass a file path or URL as options.path instead, or call JSON.parse() ' + 'on JSON text first.');
+  }
+
+  /* `import * as animationData` wraps the payload in a `default` property,
+     which lottie-web cannot read (#24, #65). */
+  if (!Array.isArray(animationData.layers) && animationData["default"]) {
+    return _normalizeAnimationData(animationData["default"], path);
+  }
+
+  /* lottie-web annotates the loaded animation (`__complete`), which throws on
+     the frozen objects produced by strict ESM bundlers (#24). */
+  if (Object.isFrozen(animationData)) {
+    return JSON.parse(JSON.stringify(animationData));
+  }
+  return animationData;
+};
 var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
   function Lottie() {
     var _this;
@@ -71,7 +100,7 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
          whether either actually changed. */
       this.animationData = animationData;
       this.colorFilters = colorFilters;
-      var filteredAnimationData = (0, _colorFilters.applyColorFilters)(animationData, colorFilters);
+      var filteredAnimationData = (0, _colorFilters.applyColorFilters)(_normalizeAnimationData(animationData, options.path), colorFilters);
       this.options = {
         container: this.el,
         renderer: renderer,
@@ -140,7 +169,7 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
         /* `options` is caller-owned and knows nothing about the wrapper, so the
            ref (already pointing at the newly rendered node) wins. */
         this.options.container = this.el;
-        this.options.animationData = (0, _colorFilters.applyColorFilters)(this.props.options.animationData, this.props.colorFilters);
+        this.options.animationData = (0, _colorFilters.applyColorFilters)(_normalizeAnimationData(this.props.options.animationData, this.props.options.path), this.props.colorFilters);
         this.anim = _lottieWeb["default"].loadAnimation(this.options);
         this.registerEvents(this.props.eventListeners);
 
@@ -179,7 +208,8 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
     value: function componentWillUnmount() {
       this.deRegisterEvents(this.props.eventListeners);
       this.destroy();
-      this.options.animationData = null;
+      /* A failed loadAnimation (e.g. invalid animationData) leaves no options. */
+      if (this.options) this.options.animationData = null;
       this.anim = null;
     }
   }, {
@@ -248,6 +278,11 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
     key: "registerEvents",
     value: function registerEvents(eventListeners) {
       var _this2 = this;
+      /* `eventListeners` is array-valued and defaults to `[]`, but a wrapper
+         component (React.lazy, an HOC, a prop spread with `null`) can hand us
+         something else. Treat anything that is not an array as "no listeners";
+         blindly calling forEach used to crash on mount and unmount (#137). */
+      if (!this.anim || !Array.isArray(eventListeners)) return;
       eventListeners.forEach(function (eventListener) {
         _this2.anim.addEventListener(eventListener.eventName, eventListener.callback);
       });
@@ -256,6 +291,7 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
     key: "deRegisterEvents",
     value: function deRegisterEvents(eventListeners) {
       var _this3 = this;
+      if (!this.anim || !Array.isArray(eventListeners)) return;
       eventListeners.forEach(function (eventListener) {
         _this3.anim.removeEventListener(eventListener.eventName, eventListener.callback);
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-lottie",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "funding": "https://opencollective.com/react-lottie",
   "description": "lottie animation view for React",
   "repository": {