react-lottie 2.4.2 → 2.5.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.5.1](https://github.com/chenqingspring/react-lottie/compare/v2.5.0...v2.5.1) (2026-11-13)
+
+### Bug Fixes
+
+* regenerate the animation when `options.renderer` changes, so a mounted component can switch between the `svg`, `canvas` and `html` engines and keeps its current frame and play/pause state; dropping the key falls back to `svg` (a change used to be silently ignored)
+
+### Documentation
+
+* document switching `options.renderer` on a mounted component, and that a light `lottie-web` build registers one renderer only
+* Storybook demo `lottie-renderer` with a live `svg` / `canvas` toggle next to both engines on their own component
+
+## [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

package/README.md

@@ -472,7 +472,8 @@ In rough order of impact:
 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.
+   both on the target device; a mounted component can switch between them
+   (see [Switch renderers](#switch-renderers-svg-canvas-html)).
 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
@@ -538,9 +539,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
@@ -550,6 +553,50 @@ 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.
+
+### Switch renderers (svg, canvas, html)
+
+`renderer` selects the engine lottie-web uses to draw the animation and belongs
+inside `options`. It defaults to `svg`; `canvas` and `html` are the other
+choices.
+
+```jsx
+const [renderer, setRenderer] = useState('svg');
+
+<Lottie options={{ animationData, loop: true, autoplay: true, renderer }} height={200} width={200} />
+<button onClick={() => setRenderer(renderer === 'svg' ? 'canvas' : 'svg')}>
+  switch renderer
+</button>
+```
+
+Changing `options.renderer` on a mounted component regenerates the animation
+with the new engine and keeps the current frame and play/pause state, so the
+toggle does not restart it. Dropping the key falls back to `svg` again. This
+needs the full `lottie-web` player: a [light build](#shrinking-the-lottie-web-bundle)
+registers a single renderer, so switching to another one fails to start.
+
+The Storybook story `lottie-renderer` demonstrates the toggle.
+
 ### Masks are missing in Safari
 
 Safari resolves the `url(#…)` references that lottie-web generates for masks,
@@ -875,7 +922,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,27 @@ 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 falls back to the SVG renderer when `options.renderer` is absent,
+   so compare the value it actually ends up with. */
+var rendererOf = function rendererOf(options) {
+  return options && options.renderer ? options.renderer : 'svg';
+};
+
 /* 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 +122,8 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
       this.animationData = animationData;
       this.colorFilters = colorFilters;
       this.locationHref = options.locationHref;
+      this.rendererSettings = rendererSettings;
+      this.renderer = rendererOf(options);
       var filteredAnimationData = (0, _colorFilters.applyColorFilters)(_normalizeAnimationData(animationData, options.path), colorFilters);
       this.options = {
         container: this.el,
@@ -159,10 +182,18 @@ 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);
+      /* `renderer` selects the engine that generates the animation (`svg`,
+         `canvas` or `html`), so it can only change by loading again. A change
+         used to be ignored, which left the animation on the old engine. */
+      var rendererChanged = this.renderer !== rendererOf(this.props.options);
       /* 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 || rendererChanged || 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 +205,16 @@ 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.renderer = rendererOf(this.props.options);
         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 or renderer would otherwise keep its old value. */
+        this.options.rendererSettings = this.props.options.rendererSettings;
+        this.options.renderer = this.renderer;
         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.2",
+  "version": "2.5.1",
   "funding": "https://opencollective.com/react-lottie",
   "description": "lottie animation view for React",
   "repository": {