react-lottie 2.3.1 → 2.3.3

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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.3](https://github.com/chenqingspring/react-lottie/compare/v2.3.2...v2.3.3) (2026-11-08)
+
+### Documentation
+
+* document animations that reference raster images: the `assets` array, the `assetsPath` option and rewriting assets to bundler-hashed URLs ([#49](https://github.com/chenqingspring/react-lottie/issues/49), [#59](https://github.com/chenqingspring/react-lottie/issues/59))
+* document aliasing `lottie-web` to `lottie_light`, `lottie_light_canvas` or `lottie_light_html` to cut the bundled player by about 45% ([#79](https://github.com/chenqingspring/react-lottie/issues/79))
+* document server-side rendering and add a regression test that renders the component in a Node process without a DOM ([#17](https://github.com/chenqingspring/react-lottie/issues/17))
+
+## [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

package/README.md

@@ -37,10 +37,76 @@ 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
-plain class components and works with React 19 as well.
+React 16.8 or newer, including React 17, React 18 and React 19. The
+`react: ">=16.8.0"` peer dependency resolves without `--legacy-peer-deps` or
+`--force`. The test suite runs against React 18; the component uses plain class
+components and works with React 17 and React 19 as well.
 
 ## Local development
 
@@ -95,7 +161,7 @@ export default class LottieControl extends React.Component {
     const defaultOptions = {
       loop: true,
       autoplay: true, 
-      animationData: animationData.default,
+      animationData,
       rendererSettings: {
         preserveAspectRatio: 'xMidYMid slice'
       }
@@ -116,6 +182,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
@@ -184,6 +255,170 @@ Finally, the file itself can usually get smaller: export at a lower precision,
 remove unused layers and precompositions, avoid embedded raster images, and let
 gzip/Brotli compress the JSON. LottieFiles' optimizer automates the first steps.
 
+### Animations with raster images
+
+An After Effects export that contains bitmap layers references those files from
+the animation's `assets` array. Each entry carries a directory (`u`), a file name
+(`p`) and an embedded flag (`e`):
+
+```json
+{ "id": "image_0", "w": 720, "h": 720, "u": "images/", "p": "img_0.png", "e": 0 }
+```
+
+With `"e": 0` lottie-web loads the file separately and resolves `u + p` relative
+to the page, which breaks as soon as the app is served from a sub-path or
+navigates client-side. Set `options.assetsPath` to the directory where the
+images are deployed instead; react-lottie forwards unknown options to
+lottie-web:
+
+```jsx
+const defaultOptions = {
+  path: '/animations/cypher.json',
+  assetsPath: '/animations/images/', // trailing slash required
+  loop: true,
+  autoplay: true,
+};
+
+<Lottie options={defaultOptions} height={400} width={400} />
+```
+
+Copy the images next to the JSON in `public/animations/images/` so they are
+served as static files instead of being bundled. `assetsPath` works with both
+`path` and `animationData`, and it applies to every image in the animation.
+
+If you want the bundler to hash and inline the images, import them yourself and
+rewrite the asset entries before passing the data. Don't mutate the imported
+JSON in place when it is a frozen ESM object:
+
+```jsx
+import img0 from './images/img_0.png';
+import animationData from './cypher.json';
+
+const data = {
+  ...animationData,
+  assets: animationData.assets.map((asset) => (
+    asset.id === 'image_0' ? { ...asset, u: '', p: img0 } : asset
+  )),
+};
+
+<Lottie options={{ animationData: data, loop: true, autoplay: true }} />
+```
+
+`"e": 1` means the image is embedded in the JSON as a base64 data URI. That
+keeps the animation self-contained, but it inflates the file by roughly a third
+and prevents the browser from caching the image separately, so prefer external
+images for anything large.
+
+### Shrinking the lottie-web bundle
+
+react-lottie imports the full `lottie-web` player (299 kB minified, 611 kB
+unminified in lottie-web 5.13), which includes the expression engine and every
+renderer. If your animations don't use expressions and you only need one
+renderer, alias `lottie-web` to a smaller build; react-lottie keeps working
+because those builds expose the same `loadAnimation` API.
+
+Vite:
+
+```js
+// vite.config.js
+export default defineConfig({
+  resolve: {
+    alias: {
+      'lottie-web': 'lottie-web/build/player/lottie_light.js',
+    },
+  },
+});
+```
+
+webpack (Create React App, Next.js):
+
+```js
+// next.config.js
+module.exports = {
+  webpack(config) {
+    config.resolve.alias['lottie-web'] = require.resolve(
+      'lottie-web/build/player/lottie_light.js'
+    );
+    return config;
+  },
+};
+```
+
+The light builds are about 45% smaller (164 kB vs 299 kB minified):
+
+* `lottie_light.js` — SVG renderer only, no expressions; shapes and raster
+  images still work.
+* `lottie_light_canvas.js` — canvas renderer only, no expressions.
+* `lottie_light_html.js` — HTML renderer only, no expressions.
+
+Pick the build that matches `options.renderer`: `lottie_light` only registers
+the SVG renderer, so pass `renderer: 'svg'` (the default); use
+`lottie_light_canvas` with `renderer: 'canvas'`. Don't alias when an animation
+uses expressions or effects, because the light builds silently skip them.
+
+### Performance on iOS and low-end devices
+
+File size mostly affects how long an animation takes to download and parse, not
+its frame rate. Once playback starts, the cost of each frame comes from what the
+renderer has to draw: the number of layers and shapes, masks and mattes,
+expressions, effects, and the pixel size of the canvas. A multi-megabyte export
+is a good signal that there is a lot of that (issue #133).
+
+On iOS 14.5, Safari, Chrome and Firefox all run on WebKit, so they render at the
+same speed; measuring in Safari is representative. Phones are also much slower
+than a desktop, so an animation that is smooth on a laptop can drop frames on
+mobile.
+
+In rough order of impact:
+
+1. **Reduce the animation.** Remove hidden and unused layers, flatten
+   precompositions, simplify masks and mattes, drop expressions and effects, and
+   avoid embedded raster images. If one scene is still heavy, split it into
+   smaller files and play only the needed range with `segments`.
+2. **Draw it at the size it is displayed.** `width` and `height` set the
+   container size; rendering a 1200 px animation into a 300 px slot does more
+   work than necessary. With the canvas renderer, also cap the backing-store
+   resolution: at a device pixel ratio of 3, a 400 px canvas is rasterized at
+   1200 px unless you set `dpr`.
+3. **Compare the renderers.** `svg` (the default) is usually fastest for a few
+   large shapes and stays crisp at any size. `canvas` avoids updating hundreds
+   of DOM nodes and often wins for animations with many small shapes. Measure
+   both on the target device.
+4. **Stop off-screen animations.** lottie-web drives every playing animation
+   from the same `requestAnimationFrame` loop, so an animation scrolled out of
+   view still costs a frame. Pause it with `isPaused`, or with `pause()` on a
+   `ref`, driven by an `IntersectionObserver`.
+
+```jsx
+const defaultOptions = {
+  animationData,
+  loop: true,
+  autoplay: true,
+  renderer: 'canvas',
+  rendererSettings: {
+    dpr: 1, // render at CSS resolution; use 2 for a sharper middle ground
+  },
+};
+
+<Lottie options={defaultOptions} height={300} width={300} />
+```
+
+For the default `svg` renderer, `rendererSettings.progressiveLoad` builds the
+layers over several frames instead of blocking on the first one. It does not
+wait for the element to scroll into view; pause off-screen animations yourself:
+
+```jsx
+// `visible` is kept up to date by an IntersectionObserver on a wrapper element.
+<Lottie
+  options={{ animationData, loop: true, autoplay: false, rendererSettings: { progressiveLoad: true } }}
+  isPaused={!visible}
+/>
+```
+
+If a reduced file still drops frames, profile it: record a timeline in Safari's
+Web Inspector while the animation plays and check whether the time goes to
+lottie-web's frame update or to the browser painting and compositing the layers.
+
 ### Play on hover
 
 `eventListeners` takes lottie-web animation events (`complete`, `loopComplete`,
@@ -211,7 +446,7 @@ export default class HoverLottie extends React.Component {
     const defaultOptions = {
       loop: false,
       autoplay: false,
-      animationData: animationData.default,
+      animationData,
       rendererSettings: {
         preserveAspectRatio: 'xMidYMid slice'
       }
@@ -298,6 +533,102 @@ The container is a `div` by default, which is not a valid child of `<p>`. Pass
 lottie-web should render into. Changing `as` reloads the animation into the new
 element and keeps the current frame.
 
+### Switch between several animations
+
+Each `<Lottie>` owns one lottie-web instance, so an app can render two
+animations side by side or keep one animation per page. To choose which one is
+shown, keep the animation data in a map and pass the entry for the current page
+as `options.animationData` (issue #128):
+
+```jsx
+import homeData from './animations/home.json';
+import aboutData from './animations/about.json';
+
+const animations = { home: homeData, about: aboutData };
+
+const PageAnimation = ({ page }) => (
+  <Lottie
+    options={{
+      loop: true,
+      autoplay: true,
+      animationData: animations[page],
+    }}
+    height={300}
+    width={300}
+  />
+);
+```
+
+Changing `options.animationData` reloads the animation into the same container,
+so a `key` is not required. Keep the JSON modules stable: copying the data in
+`render` (`animationData: { ...animations[page] }`) hands the component a new
+object on every render and reloads the animation each time. If you do want to
+start over — to replay an intro, for example — give the component a `key` so
+React unmounts and remounts it:
+
+```jsx
+<Lottie key={page} options={{ ...defaultOptions, animationData: animations[page] }} />
+```
+
+Unmounting destroys the lottie-web instance, so only the visible page animates.
+When the files are large, load them with `options.path` and fetch the JSON for
+the next page ahead of time instead of shipping every animation in one bundle;
+see [Loading animation data without bloating the bundle](#loading-animation-data-without-bloating-the-bundle).
+
+### Server-side rendering
+
+`<Lottie />` renders only a sized container element on the server; lottie-web is
+imported but instantiated in `componentDidMount` only, so `renderToString` (and
+Next.js/Gatsby prerendering) works and the animation starts after hydration:
+
+```jsx
+// server output: <div style="width:400px;height:400px;..."></div>
+<Lottie options={defaultOptions} height={400} width={400} />
+```
+
+Importing the package outside a browser no longer throws
+`ReferenceError: window is not defined`; lottie-web guards its DOM access at
+module load. If your bundler still evaluates the player on the server, load the
+component without SSR:
+
+```jsx
+// Next.js
+import dynamic from 'next/dynamic';
+
+const Lottie = dynamic(() => import('react-lottie'), { ssr: false });
+```
+
+Animations loaded from `options.path` are fetched by lottie-web after mount, so
+nothing is requested during the server render. Avoid the hydration trap
+described in [Animations and page navigation](#animations-and-page-navigation)
+when the container is nested in a `<p>`.
+
+### Animations and page navigation
+
+react-lottie creates a lottie-web instance when the component mounts and calls
+`destroy()` on unmount, so client-side navigation is safe as long as the page
+really unmounts. A layout that renders every page at once (or keeps pages
+mounted when switching tabs) keeps every animation running; mount only the
+visible one.
+
+One non-obvious trap on SSR frameworks such as Gatsby or Next.js: the wrapper is
+a `div` by default, and a `div` inside a `p` is invalid HTML. The browser moves
+the `div` out of the paragraph while parsing the server-rendered page, React
+reports a hydration mismatch (`validateDOMNesting`), and the animation node ends
+up outside the page subtree. Navigating back and forth can then leave animation
+nodes behind. Render the animation with `as="span"` (issue #73) or move it
+outside the paragraph:
+
+```jsx
+<p>
+  Text <Lottie as="span" options={defaultOptions} /> more text
+</p>
+```
+
+If animations still accumulate, confirm that each page unmounts (React DevTools
+shows the component tree changing), and pause off-screen instances as described
+in [Performance on iOS and low-end devices](#performance-on-ios-and-low-end-devices).
+
 ### Imperative control
 
 A `ref` to the component exposes `play()`, `pause()`, `stop()`,
@@ -329,7 +660,7 @@ the object representing the animation settings that will be instantiated by body
 >
 >**path** *optional* — a URL (or path) to a JSON animation file. Mutually exclusive with `animationData`.
 >
->**renderer** *optional* [default: `svg`]
+>**renderer** *optional* [default: `svg`] — `svg`, `canvas` or `html`. See [Performance on iOS and low-end devices](#performance-on-ios-and-low-end-devices).
 >
 >**rendererSettings** *required* 
 

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;
     }
   }, {

package/package.json

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