react-lottie 2.3.3 → 2.4.1

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 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.4.1](https://github.com/chenqingspring/react-lottie/compare/v2.4.0...v2.4.1) (2026-11-08)
+
+### Documentation
+
+* explain that `rendererSettings` belongs inside `options`, not on `<Lottie />`, and how `preserveAspectRatio` fits (`meet`), crops (`slice`) or stretches (`none`) an animation ([#98](https://github.com/chenqingspring/react-lottie/issues/98))
+* explain why an embedded base64 image can raise `Invalid or unexpected token` from an `eval` inside a lottie expression, and how to find the offending expression ([#88](https://github.com/chenqingspring/react-lottie/issues/88))
+* document taking a presentational animation out of the tab order and exposing it to screen readers with `tabIndex`, `ariaRole` and `ariaLabel` ([#130](https://github.com/chenqingspring/react-lottie/issues/130))
+* add a Storybook demo of the `preserveAspectRatio` modes on a square animation in a wide container
+
+## [2.4.0](https://github.com/chenqingspring/react-lottie/compare/v2.3.3...v2.4.0) (2026-11-08)
+
+### Features
+
+* apply `options.locationHref` before loading, so Safari keeps the masks, mattes, gradients and filters that lottie-web bakes into `url(#id)` references when the page uses a `<base>` tag or is served from a sub-path; changing it reloads the animation ([#111](https://github.com/chenqingspring/react-lottie/issues/111))
+* expose the container `margin` as a prop, accepting any CSS `margin` value or a number of pixels (default `0 auto`), applied before `style` so an explicit `style.margin` still wins ([#107](https://github.com/chenqingspring/react-lottie/issues/107))
+
+### Documentation
+
+* explain how to load animation data from a URL and why a URL belongs in `options.path`, not `animationData` ([#106](https://github.com/chenqingspring/react-lottie/issues/106))
+* explain the default click-to-pause behaviour and the `isClickToPauseDisabled` opt-out ([#110](https://github.com/chenqingspring/react-lottie/issues/110))
+* state that the `componentWill*` lifecycles deprecated in React 16.3 and removed in React 17 are not used ([#112](https://github.com/chenqingspring/react-lottie/issues/112), [#119](https://github.com/chenqingspring/react-lottie/issues/119))
+
 ## [2.3.3](https://github.com/chenqingspring/react-lottie/compare/v2.3.2...v2.3.3) (2026-11-08)
 
 ### Documentation

package/README.md

@@ -108,6 +108,13 @@ React 16.8 or newer, including React 17, React 18 and React 19. The
 `--force`. The test suite runs against React 18; the component uses plain class
 components and works with React 17 and React 19 as well.
 
+The component is a class, but it only uses the lifecycles React still supports
+(`componentDidMount`, `componentDidUpdate`, `componentWillUnmount`). The
+`componentWill*` methods that React 16.3 deprecated and React 17 stopped
+calling were removed in 2.0.0, so React 17 and newer do not warn about legacy
+lifecycles or skip the data/`path` reload ([#77](https://github.com/chenqingspring/react-lottie/issues/77),
+[#119](https://github.com/chenqingspring/react-lottie/issues/119)).
+
 ## Local development
 
 Run the Storybook stories with `npm start` (port 9010) and the test suite with
@@ -187,6 +194,53 @@ belongs in `options.path`; a namespace import
 (`import * as animationData`) is unwrapped automatically but the default import
 above is preferred.
 
+### Loading animation data from a URL
+
+Put the URL in `options.path`, not `options.animationData`. `animationData` is
+the parsed JSON object; lottie-web cannot fetch a string, so react-lottie throws
+an explanatory error if you pass one (issue #106):
+
+```jsx
+const defaultOptions = {
+  path: 'https://someurl.com/animationData.json',
+  loop: true,
+  autoplay: true,
+};
+
+<Lottie options={defaultOptions} width="1293px" height="300px" />
+```
+
+`path` accepts an absolute URL, a site-root path or a relative path. lottie-web
+fetches it after mount (nothing is requested during server rendering), and
+changing `path` reloads the animation. Because lottie-web owns the request,
+`colorFilters` is not applied — fetch the JSON yourself and pass the parsed
+object as `animationData` if you need to recolor it or send request headers:
+
+```jsx
+import { useEffect, useState } from 'react';
+
+function RemoteAnimation() {
+  const [animationData, setAnimationData] = useState(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    fetch('https://someurl.com/animationData.json')
+      .then((response) => response.json())
+      .then((data) => { if (!cancelled) setAnimationData(data); });
+    return () => { cancelled = true; };
+  }, []);
+
+  if (!animationData) return null;
+
+  return (
+    <Lottie options={{ animationData, loop: true, autoplay: true }} height={300} />
+  );
+}
+```
+
+See [Loading animation data without bloating the bundle](#loading-animation-data-without-bloating-the-bundle)
+for the bundle-size trade-offs between these approaches.
+
 ### Loading animation data without bloating the bundle
 
 A static import like `import animationData from './pinjump.json'` (the example
@@ -309,6 +363,35 @@ 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.
 
+### `Invalid or unexpected token` with embedded images
+
+Embedded base64 images do work: an asset with `"e": 1` and a `p` value that
+starts with `data:image/png;base64,` is decoded like any other image, and the
+layer only has to reference it through `refId`.
+
+The `Uncaught SyntaxError: Invalid or unexpected token` thrown from
+`eval (eval at initiateExpression ...)` is not about the image. It comes from an
+**expression** inside the animation. lottie-web compiles expressions with
+`eval` when the animation loads. Newer After Effects versions can save an
+expression in an encoded `@JSXBIN@…` form, which lottie-web cannot parse, so
+the `eval` throws while the layer's effects are prepared
+(`IImageElement.prepareProperties`). The same error can appear in animations
+with no images at all.
+
+Fixes, in order of preference:
+
+- Remove the expressions in After Effects, or bake them to keyframes
+  (**Animation → Keyframe Assistant → Convert Expression to Keyframes**), then
+  export again. The animation keeps looking the same without runtime
+  evaluation.
+- Keep the expression only if it is plain JavaScript, and make sure a Content
+  Security Policy is not blocking `eval` (it needs `'unsafe-eval'`). Otherwise
+  move that behaviour out of the animation.
+- If the expression is not needed for playback, alias `lottie-web` to one of
+  the [light builds](#shrinking-the-lottie-web-bundle): they have no expression
+  engine and skip expressions instead of throwing. They skip the effect's
+  behaviour too, so only do this when the visual result is acceptable.
+
 ### Shrinking the lottie-web bundle
 
 react-lottie imports the full `lottie-web` player (299 kB minified, 611 kB
@@ -419,6 +502,94 @@ 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.
 
+### Fit or crop an animation (preserveAspectRatio)
+
+The SVG that lottie-web generates has its own `viewBox`, and the browser scales
+it to the container according to `preserveAspectRatio`. lottie-web's default is
+`xMidYMid meet`, which letterboxes the animation. Use `xMidYMid slice` to fill
+the container and crop the overflow instead, or `none` to stretch it.
+
+`rendererSettings` belongs **inside `options`**, next to `animationData` or
+`path`. A `rendererSettings` prop on `<Lottie />` itself is ignored, because the
+component only forwards `options` to `lottie.loadAnimation()`:
+
+```jsx
+const defaultOptions = {
+  animationData,
+  loop: true,
+  autoplay: true,
+  rendererSettings: {
+    preserveAspectRatio: 'xMidYMid slice',
+  },
+};
+
+// A wide box for a square animation, so `slice` has something to crop.
+<Lottie options={defaultOptions} height={200} width={400} />
+```
+
+Two things make a working setting look broken:
+
+- `meet` and `slice` render identically when the container has the same aspect
+  ratio as the animation. Sizing a square animation with `height={400}
+  width={400}` leaves nothing to crop or letterbox.
+- The value is applied when the animation loads. Changing
+  `options.rendererSettings` on a mounted component does not re-apply it;
+  remount the animation (or change its `key`) to pick up a new value.
+
+If the `<svg>` in the inspector still lacks `preserveAspectRatio`, check what
+you pass as `options.animationData`. An ES module namespace
+(`import * as animationData`) is unwrapped for you, but any payload lottie-web
+cannot read leaves it without a `viewBox`, so the attribute has nothing to
+scale. See [Usage](#usage).
+
+The canvas renderer reads `preserveAspectRatio` too.
+
+### Masks are missing in Safari
+
+Safari resolves the `url(#…)` references that lottie-web generates for masks,
+mattes, gradients and filters against the document's base URL. When the page
+has a `<base href>` tag, or the animation is served from a path the browser
+resolves differently, those references point at the wrong document and Safari
+renders the animation without its masks. Chrome and Firefox usually still find
+them.
+
+lottie-web's documented workaround is to call `lottie.setLocationHref()` before
+the animation is generated. react-lottie exposes it as `options.locationHref`:
+
+```jsx
+const defaultOptions = {
+  animationData,
+  loop: true,
+  autoplay: true,
+  locationHref: window.location.href,
+};
+
+<Lottie options={defaultOptions} height={400} width={400} />
+```
+
+Pass the URL the page is actually served from, without the `#` fragment.
+lottie-web joins the value with `#<id>` when it builds the references, so a
+fragment produces broken URLs. The value is global to lottie-web, so pass the
+same `locationHref` to every `<Lottie />` on the page. Changing it regenerates
+the animation, because the base URL is baked into the generated markup.
+
+If you already import lottie-web yourself, calling the function directly works
+too, as long as the bundler resolves it to the same copy react-lottie uses:
+
+```js
+import lottie from 'lottie-web';
+
+lottie.setLocationHref(window.location.href);
+```
+
+Run that before the first animation mounts, for example at application startup.
+
+If the masks are still missing with the correct href, the artwork is the likely
+cause: complex masks and alpha mattes are the least reliable part of the SVG
+renderer. Compare with the [canvas renderer](#performance-on-ios-and-low-end-devices),
+or open the same JSON in lottie-web's own preview to confirm the problem is
+renderer-level rather than a react-lottie bug.
+
 ### Play on hover
 
 `eventListeners` takes lottie-web animation events (`complete`, `loopComplete`,
@@ -467,6 +638,42 @@ export default class HoverLottie extends React.Component {
 
 ```
 
+### Click to pause
+
+Clicking or tapping the animation pauses it, and clicking again resumes it.
+This is on by default: the container also has `ariaRole="button"`, so an
+animation that looks decorative is still an interactive control (issue
+[#110](https://github.com/chenqingspring/react-lottie/issues/110)).
+
+Disable it when the animation is decorative, or when you want a click to do
+something else:
+
+```jsx
+<Lottie options={defaultOptions} isClickToPauseDisabled />
+```
+
+A decorative animation should also leave the tab order. Pair
+`isClickToPauseDisabled` with `tabIndex={-1}` so keyboard users do not land on
+an animation they cannot interact with (issue
+[#130](https://github.com/chenqingspring/react-lottie/issues/130)):
+
+```jsx
+<Lottie options={defaultOptions} isClickToPauseDisabled tabIndex={-1} />
+```
+
+The component has no `onClick` prop. Put your handler on a wrapper element
+instead; the click bubbles from the animation container to the wrapper:
+
+```jsx
+<div onClick={() => openDetails()}>
+  <Lottie options={defaultOptions} isClickToPauseDisabled />
+</div>
+```
+
+Without `isClickToPauseDisabled` both run: playback toggles and the wrapper's
+handler still fires after it. Leave the prop out when you want click-to-pause as
+well.
+
 ### Play a segment
 
 Pass `segments` to play a frame range instead of the whole animation. The
@@ -525,7 +732,7 @@ The container is a `div` by default, which is not a valid child of `<p>`. Pass
 
 ```jsx
 <p>
-  Text <Lottie as="span" options={defaultOptions} ariaRole="img" /> more text
+  Text <Lottie as="span" options={defaultOptions} ariaRole="img" tabIndex={-1} /> more text
 </p>
 ```
 
@@ -662,7 +869,9 @@ the object representing the animation settings that will be instantiated by body
 >
 >**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* 
+>**rendererSettings** *optional* — settings forwarded to lottie-web's renderer, such as `preserveAspectRatio`, `progressiveLoad`, `className` and `id`. Must be inside `options`, not a prop on `<Lottie />`. Read once when the animation loads. See [Fit or crop an animation](#fit-or-crop-an-animation-preserveaspectratio).
+>
+>**locationHref** *optional* — the base URL lottie-web writes into its SVG mask, matte, gradient and filter references, applied with `setLocationHref()` before the animation is generated. Use it when Safari drops masks because of a `<base>` tag. See [Masks are missing in Safari](#masks-are-missing-in-safari).
 
 **colorFilters** *optional* [default: `[]`]
 
@@ -677,6 +886,17 @@ pixel value for containers width.
 
 pixel value for containers height.
 
+**margin** *optional* [default: `0 auto`]
+
+Margin of the container. Accepts any CSS `margin` value (`'20px'`,
+`'10px auto'`, `'1rem 2rem'`) or a number of pixels. Use it instead of
+`style.margin` when the default `0 auto` misbehaves in a browser (issue #107).
+`style` is merged after this prop, so an explicit `style.margin` still wins.
+
+```jsx
+<Lottie options={defaultOptions} margin="10px auto" />
+```
+
 **isStopped** *optional* [default: `false`]
 
 Stops the animation and resets it to the first frame. Setting it back to `false`
@@ -726,7 +946,11 @@ eventListeners=[
 ```
 
 **isClickToPauseDisabled** *optional* [default: `false`]
-When this props is left unspecified or is set to `false` animations are paused or resumed when a user clicks or taps them. If you do not want this behaviour set this prop to `true`.
+
+When this prop is left unspecified or is set to `false`, animations are paused
+or resumed when a user clicks or taps them. If you do not want this behaviour,
+set this prop to `true`. See [Click to pause](#click-to-pause) for a custom
+click handler.
 
 **ariaRole** *optional* [default: `button`]
 
@@ -743,12 +967,14 @@ Accessible name of the container.
 
 **style** *optional*
 
-Extra inline styles merged onto the container, after the `width`, `height` and
-layout defaults. Use it to override `overflow` or `margin`.
+Extra inline styles merged onto the container, after the `width`, `height`,
+`margin` and layout defaults. Use it to override `overflow`, for example.
 
 **tabIndex** *optional* [default: `0`]
 Tab order of the rendered container. Pass `-1` for a purely presentational
-animation that should not receive keyboard focus.
+animation that should not receive keyboard focus (issue
+[#130](https://github.com/chenqingspring/react-lottie/issues/130)); combine it
+with `isClickToPauseDisabled` as shown in [Click to pause](#click-to-pause).
 
 **as** *optional* [default: `div`]
 
@@ -757,6 +983,50 @@ Element or component rendered as the animation container. Use `as="span"` when
 custom component must forward its `ref` to a DOM element. See
 [Render inline inside a paragraph](#render-inline-inside-a-paragraph).
 
+## Hooks and alternatives
+
+`react-lottie` is deliberately a thin class component over lottie-web. Its
+public API is the imperative instance on a `ref` (`play`, `pause`,
+`goToAndStop`, `goToAndPlay`, `playSegments`), so replacing the class with a
+hooks-only component would break every existing app without changing what is
+rendered. You do not need hooks to drive it declaratively, though: changing
+`options.animationData` or `options.path` reloads the animation, and changes to
+`segments`, `isPaused`, `isStopped`, `speed`, `direction` and `colorFilters`
+are applied to the running instance. A function component can hold the state
+around it (issue #117):
+
+```jsx
+import React, { useState } from 'react'
+import Lottie from 'react-lottie';
+import animationData from './pinjump.json'
+
+export default function Player() {
+  const [segment, setSegment] = useState([0, 30]);
+  const options = { animationData, loop: true };
+
+  return (
+    <div>
+      <Lottie options={options} segments={segment} width={240} height={240} />
+      <button onClick={() => setSegment([30, 60])}>next part</button>
+    </div>
+  );
+}
+```
+
+If you specifically want a hook-first API, use one of these wrappers instead:
+
+* [react-lottie-player](https://github.com/mifi/react-lottie-player) — the
+  `useLottie` hook, with `path` and `animationData` support (v2.1.0, last
+  published July 2024).
+* [lottie-react](https://github.com/Gamote/lottie-react) — actively
+  maintained, hooks-based API (v3.1.2).
+* [@lottiefiles/react-lottie-player](https://github.com/LottieFiles/lottie-react)
+  — LottieFiles' official wrapper, for LottieFiles-specific features
+  (v3.6.0).
+
+All of them wrap the same lottie-web runtime, so switching mostly changes the
+component API rather than how the animation is rendered.
+
 ## Related Projects
 
 * [lottie-web](https://github.com/airbnb/lottie-web) react-lottie is a wrapper of lottie-web

package/dist/index.js

@@ -100,6 +100,7 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
          whether either actually changed. */
       this.animationData = animationData;
       this.colorFilters = colorFilters;
+      this.locationHref = options.locationHref;
       var filteredAnimationData = (0, _colorFilters.applyColorFilters)(_normalizeAnimationData(animationData, options.path), colorFilters);
       this.options = {
         container: this.el,
@@ -117,6 +118,10 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
       if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production' && Array.isArray(colorFilters) && colorFilters.length > 0 && !animationData) {
         console.warn('[react-lottie] colorFilters requires options.animationData; ' + 'animations loaded from options.path are not recolored.');
       }
+
+      /* Must happen before the animation is generated: lottie-web bakes the base
+         URL into its mask, matte, gradient and filter references (issue #111). */
+      this.setLocationHref(options);
       this.anim = _lottieWeb["default"].loadAnimation(this.options);
       this.registerEvents(eventListeners);
       this.setSpeed();
@@ -151,10 +156,13 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
       var dataChanged = this.animationData !== this.props.options.animationData;
       var pathChanged = this.options.path !== this.props.options.path;
       var colorFiltersChanged = !(0, _colorFilters.colorFiltersAreEqual)(this.colorFilters, this.props.colorFilters);
+      /* lottie-web bakes the base URL into each generated `url(#id)` reference,
+         so a new href only takes effect when the animation is generated again. */
+      var locationHrefChanged = this.locationHref !== this.props.options.locationHref;
       /* The wrapper element is part of lottie-web's configuration, so a new
          element means the animation has to be bound to the new node. */
       var containerChanged = prevProps.as !== this.props.as;
-      if (dataChanged || pathChanged || colorFiltersChanged || containerChanged) {
+      if (dataChanged || pathChanged || colorFiltersChanged || locationHrefChanged || containerChanged) {
         var currentFrame = this.anim ? this.anim.currentFrame : 0;
         var wasPaused = this.anim ? this.anim.isPaused : true;
         /* lottie-web cannot recolor a loaded animation and cannot move one to
@@ -165,11 +173,13 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
         this.destroy();
         this.animationData = this.props.options.animationData;
         this.colorFilters = this.props.colorFilters;
+        this.locationHref = this.props.options.locationHref;
         this.options = _objectSpread(_objectSpread({}, this.options), this.props.options);
         /* `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)(_normalizeAnimationData(this.props.options.animationData, this.props.options.path), this.props.colorFilters);
+        this.setLocationHref(this.options);
         this.anim = _lottieWeb["default"].loadAnimation(this.options);
         this.registerEvents(this.props.eventListeners);
 
@@ -231,6 +241,22 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
     value: function setSubframe() {
       this.anim.setSubframe(this.props.isSubframe);
     }
+
+    /* lottie-web writes its internal mask, matte, gradient and filter references
+       as `url(<locationHref>#id)`. Safari resolves them against the page's base
+       URL, so a `<base href>` (or a mismatched asset URL) makes it drop the
+       masks; other browsers are more forgiving. lottie-web's documented fix is
+       the global `setLocationHref()`, which has to run before the animation is
+       generated (issue #111). Passing `options.locationHref` lets callers do
+       that without importing lottie-web themselves, which also works when the
+       bundler gives them a different copy of the player. */
+  }, {
+    key: "setLocationHref",
+    value: function setLocationHref(options) {
+      if (options.locationHref != null) {
+        _lottieWeb["default"].setLocationHref(options.locationHref);
+      }
+    }
   }, {
     key: "play",
     value: function play() {
@@ -303,6 +329,7 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
       var _this$props2 = this.props,
         width = _this$props2.width,
         height = _this$props2.height,
+        margin = _this$props2.margin,
         ariaRole = _this$props2.ariaRole,
         ariaLabel = _this$props2.ariaLabel,
         isClickToPauseDisabled = _this$props2.isClickToPauseDisabled,
@@ -322,7 +349,9 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
         width: getSize(width),
         height: getSize(height),
         overflow: 'hidden',
-        margin: '0 auto',
+        /* `margin` is a prop so callers do not have to fight the default through
+           `style` on browsers where centring with `0 auto` misbehaves (#107). */
+        margin: getSize(margin),
         outline: 'none'
       }, this.props.style);
       var onClickHandler = isClickToPauseDisabled ? function () {
@@ -357,6 +386,7 @@ Lottie.propTypes = {
   })),
   height: _propTypes["default"].oneOfType([_propTypes["default"].string, _propTypes["default"].number]),
   width: _propTypes["default"].oneOfType([_propTypes["default"].string, _propTypes["default"].number]),
+  margin: _propTypes["default"].oneOfType([_propTypes["default"].string, _propTypes["default"].number]),
   isStopped: _propTypes["default"].bool,
   isPaused: _propTypes["default"].bool,
   speed: _propTypes["default"].number,
@@ -383,5 +413,6 @@ Lottie.defaultProps = {
   isClickToPauseDisabled: false,
   title: '',
   tabIndex: 0,
-  as: 'div'
+  as: 'div',
+  margin: '0 auto'
 };

package/package.json

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