react-lottie 2.4.1 → 2.5.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 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.5.0](https://github.com/chenqingspring/react-lottie/compare/v2.4.2...v2.5.0) (2026-11-10)
+
+### Features
+
+* regenerate the animation when `options.rendererSettings` changes, so `preserveAspectRatio` and the other renderer settings can be switched on a mounted component; the current frame and play/pause state are kept, and recreating an equal object does not reload anything ([#98](https://github.com/chenqingspring/react-lottie/issues/98))
+* Storybook demo of the live `preserveAspectRatio` toggle next to the three static modes
+
+### Documentation
+
+* document switching `rendererSettings` on a mounted component instead of remounting the animation ([#98](https://github.com/chenqingspring/react-lottie/issues/98))
+
+## [2.4.2](https://github.com/chenqingspring/react-lottie/compare/v2.4.1...v2.4.2) (2026-11-09)
+
+### Documentation
+
+* state that there is no npm version requirement, and why 1.x printed an `Unsupported engine` warning with npm 6 and newer ([#87](https://github.com/chenqingspring/react-lottie/issues/87))
+
 ## [2.4.1](https://github.com/chenqingspring/react-lottie/compare/v2.4.0...v2.4.1) (2026-11-08)
 
 ### Documentation

package/README.md

@@ -108,6 +108,12 @@ 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.
 
+There is no npm version requirement. 1.x declared
+`"engines": { "npm": "^3.0.0" }`, so npm 6 and newer printed an
+`Unsupported engine` warning on install; that field was removed before 2.0.0
+([#87](https://github.com/chenqingspring/react-lottie/issues/87)). Install with
+any npm version that can resolve the React peer dependency.
+
 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
@@ -532,9 +538,11 @@ 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.
+- The value is applied when the renderer is generated. Changing
+  `options.rendererSettings` on a mounted component regenerates the animation
+  and keeps the current frame and playback state, so a live toggle works; a
+  render that recreates an object with the same values does not reload
+  anything. See [Fit or crop, live](#fit-or-crop-live).
 
 If the `<svg>` in the inspector still lacks `preserveAspectRatio`, check what
 you pass as `options.animationData`. An ES module namespace
@@ -544,6 +552,27 @@ scale. See [Usage](#usage).
 
 The canvas renderer reads `preserveAspectRatio` too.
 
+#### Fit or crop, live
+
+`rendererSettings` can be switched after mount. The animation is regenerated
+with the new settings and the current frame plus play/pause state are restored,
+so a `meet`/`slice` toggle does not restart a half-played animation:
+
+```jsx
+const [mode, setMode] = useState('xMidYMid meet');
+
+<Lottie
+  options={{ animationData, loop: true, autoplay: true, rendererSettings: { preserveAspectRatio: mode } }}
+  height={200}
+  width={400}
+/>
+<button onClick={() => setMode(mode === 'xMidYMid meet' ? 'xMidYMid slice' : 'xMidYMid meet')}>
+  toggle fit / crop
+</button>
+```
+
+The Storybook story `lottie-renderer-settings` demonstrates the same toggle.
+
 ### Masks are missing in Safari
 
 Safari resolves the `url(#…)` references that lottie-web generates for masks,
@@ -869,7 +898,7 @@ 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** *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).
+>**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 />`. Changing it regenerates the animation and keeps the current frame and playback state. 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).
 

package/dist/index.js

@@ -9,7 +9,6 @@ var _propTypes = _interopRequireDefault(require("prop-types"));
 var _lottieWeb = _interopRequireDefault(require("lottie-web"));
 var _colorFilters = require("./colorFilters");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { "default": e }; }
-function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
 function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
 function _classCallCheck(a, n) { if (!(a instanceof n)) throw new TypeError("Cannot call a class as a function"); }
@@ -25,6 +24,7 @@ function _setPrototypeOf(t, e) { return _setPrototypeOf = Object.setPrototypeOf
 function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
 function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : i + ""; }
 function _toPrimitive(t, e) { if ("object" != _typeof(t) || !t) return t; var r; if ("undefined" != typeof Symbol && void 0 !== (r = t[Symbol.toPrimitive])) { var i = r.call(t, e || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === e ? String : Number)(t); }
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
 var segmentsAreEqual = function segmentsAreEqual(a, b) {
   if (a === b) return true;
   if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
@@ -33,6 +33,21 @@ var segmentsAreEqual = function segmentsAreEqual(a, b) {
   });
 };
 
+/* `rendererSettings` is usually written as an object literal inside `options`,
+   so a re-render creates a new object even when nothing changed. Compare the
+   values, not the identity, to avoid reloading the animation on every render
+   while still reacting to a real change (issue #98). */
+var rendererSettingsAreEqual = function rendererSettingsAreEqual(a, b) {
+  if (a === b) return true;
+  if (a == null || b == null) return a == null && b == null;
+  if (_typeof(a) !== 'object' || _typeof(b) !== 'object') return false;
+  var keys = Object.keys(a);
+  if (keys.length !== Object.keys(b).length) return false;
+  return keys.every(function (key) {
+    return Object.prototype.hasOwnProperty.call(b, key) && a[key] === b[key];
+  });
+};
+
 /* 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
@@ -101,6 +116,7 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
       this.animationData = animationData;
       this.colorFilters = colorFilters;
       this.locationHref = options.locationHref;
+      this.rendererSettings = rendererSettings;
       var filteredAnimationData = (0, _colorFilters.applyColorFilters)(_normalizeAnimationData(animationData, options.path), colorFilters);
       this.options = {
         container: this.el,
@@ -159,10 +175,14 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
       /* 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;
+      /* `preserveAspectRatio`, `progressiveLoad` and the other renderer settings
+         are read by lottie-web when it generates the renderer, so a change has to
+         regenerate the animation too (issue #98). */
+      var rendererSettingsChanged = !rendererSettingsAreEqual(this.rendererSettings, this.props.options.rendererSettings);
       /* 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 || locationHrefChanged || containerChanged) {
+      if (dataChanged || pathChanged || colorFiltersChanged || locationHrefChanged || rendererSettingsChanged || 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
@@ -174,10 +194,14 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
         this.animationData = this.props.options.animationData;
         this.colorFilters = this.props.colorFilters;
         this.locationHref = this.props.options.locationHref;
+        this.rendererSettings = this.props.options.rendererSettings;
         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;
+        /* Spreading does not delete a key the caller dropped, so a removed
+           rendererSettings would otherwise keep its old value. */
+        this.options.rendererSettings = this.props.options.rendererSettings;
         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);

package/package.json

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