react-lottie 2.5.0 → 2.5.1

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 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

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
@@ -573,6 +574,29 @@ const [mode, setMode] = useState('xMidYMid meet');
 
 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,

package/dist/index.js

@@ -48,6 +48,12 @@ var rendererSettingsAreEqual = function rendererSettingsAreEqual(a, b) {
   });
 };
 
+/* 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
@@ -117,6 +123,7 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
       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,
@@ -179,10 +186,14 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
          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 || rendererSettingsChanged || 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
@@ -195,13 +206,15 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
         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 would otherwise keep its old value. */
+           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.5.0",
+  "version": "2.5.1",
   "funding": "https://opencollective.com/react-lottie",
   "description": "lottie animation view for React",
   "repository": {