react-lottie 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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.0](https://github.com/chenqingspring/react-lottie/compare/v2.2.0...v2.3.0) (2026-11-05)
+
+### Features
+
+* add an `as` prop to choose the element rendered around the animation, so `<Lottie as="span" />` can be nested in a `<p>` without invalid HTML. Changing `as` rebinds the animation to the new node and keeps the current frame ([#73](https://github.com/chenqingspring/react-lottie/issues/73))
+
 ## [2.2.0](https://github.com/chenqingspring/react-lottie/compare/v2.1.0...v2.2.0) (2026-11-05)
 
 ### Features

package/README.md

@@ -116,6 +116,74 @@ export default class LottieControl extends React.Component {
 
 ```
 
+### Loading animation data without bloating the bundle
+
+A static import like `import animationData from './pinjump.json'` (the example
+above) makes the bundler inline the animation into the JavaScript chunk that
+imports it. A 500 kB JSON file then becomes 500 kB of JavaScript the browser has
+to download and parse before the page can run. The JSON is data, not code, so
+keep it out of the main bundle:
+
+**Serve it from `public/` and use `options.path`.** In Create React App, Vite
+and Next.js, files in `public/` are copied to the build output as static
+assets; they are not bundled into JavaScript. `lottie-web` fetches the file when
+the component mounts, and the browser caches it separately from the app bundle:
+
+```jsx
+const defaultOptions = {
+  path: '/animations/pinjump.json', // relative to the deployed site root
+  loop: true,
+  autoplay: true,
+  rendererSettings: {
+    preserveAspectRatio: 'xMidYMid slice'
+  }
+};
+
+<Lottie options={defaultOptions} height={400} width={400} />
+```
+
+Because lottie-web owns the fetch, `colorFilters` is not applied to animations
+loaded this way — fetch the JSON yourself if you need to recolor it.
+
+**Or load it on demand with a dynamic `import()`.** If you need the parsed data
+in your own code, a dynamic import puts the JSON in a separate chunk that is
+downloaded only when the component renders:
+
+```jsx
+import { useEffect, useState } from 'react';
+import Lottie from 'react-lottie';
+
+export default function Animation() {
+  const [animationData, setAnimationData] = useState(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    import('./pinjump.json').then(({ default: data }) => {
+      if (!cancelled) setAnimationData(data);
+    });
+    return () => { cancelled = true; };
+  }, []);
+
+  if (!animationData) return null;
+
+  return (
+    <Lottie
+      options={{ animationData, loop: true, autoplay: true }}
+      height={400}
+      width={400}
+    />
+  );
+}
+```
+
+Rendering `<Animation />` lazily (for example when it scrolls into view) defers
+even that chunk until it is needed. The same idea works with `React.lazy` around
+a component that imports the JSON.
+
+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.
+
 ### Play on hover
 
 `eventListeners` takes lottie-web animation events (`complete`, `loopComplete`,
@@ -215,6 +283,21 @@ frame and paused/playing state are preserved. Animations loaded from
 `options.path` are not recolored, since the JSON is fetched by lottie-web:
 load the JSON yourself and pass it as `animationData` instead.
 
+### Render inline inside a paragraph
+
+The container is a `div` by default, which is not a valid child of `<p>`. Pass
+`as` to choose the element (issue #73):
+
+```jsx
+<p>
+  Text <Lottie as="span" options={defaultOptions} ariaRole="img" /> more text
+</p>
+```
+
+`as` accepts a tag name or a component that forwards its `ref` to the DOM node
+lottie-web should render into. Changing `as` reloads the animation into the new
+element and keeps the current frame.
+
 ### Imperative control
 
 A `ref` to the component exposes `play()`, `pause()`, `stop()`,
@@ -336,6 +419,13 @@ layout defaults. Use it to override `overflow` or `margin`.
 Tab order of the rendered container. Pass `-1` for a purely presentational
 animation that should not receive keyboard focus.
 
+**as** *optional* [default: `div`]
+
+Element or component rendered as the animation container. Use `as="span"` when
+`<Lottie />` is a child of `<p>`, where a `div` is invalid HTML (issue #73). A
+custom component must forward its `ref` to a DOM element. See
+[Render inline inside a paragraph](#render-inline-inside-a-paragraph).
+
 ## Related Projects
 
 * [lottie-web](https://github.com/airbnb/lottie-web) react-lottie is a wrapper of lottie-web

package/dist/index.js

@@ -122,24 +122,31 @@ 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);
-      if (dataChanged || pathChanged || colorFiltersChanged) {
+      /* 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) {
         var currentFrame = this.anim ? this.anim.currentFrame : 0;
         var wasPaused = this.anim ? this.anim.isPaused : true;
-        /* lottie-web cannot recolor a loaded animation, so a filter change has to
-           load the data again. Only a filter-only change restores the frame. */
-        var colorOnlyChange = colorFiltersChanged && !dataChanged && !pathChanged;
+        /* lottie-web cannot recolor a loaded animation and cannot move one to
+           another node, so those changes load the same data again. Only then is
+           it worth restoring the frame and playback state. */
+        var reloadInPlace = !dataChanged && !pathChanged;
         this.deRegisterEvents(prevProps.eventListeners);
         this.destroy();
         this.animationData = this.props.options.animationData;
         this.colorFilters = this.props.colorFilters;
         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)(this.props.options.animationData, this.props.colorFilters);
         this.anim = _lottieWeb["default"].loadAnimation(this.options);
         this.registerEvents(this.props.eventListeners);
 
-        /* Keep the frame and playback state so a theme change does not restart
-           a paused or half-played animation. */
-        if (colorOnlyChange) {
+        /* Keep the frame and playback state so a theme or element change does
+           not restart a paused or half-played animation. */
+        if (reloadInPlace) {
           if (this.props.segments) this.anim.playSegments(this.props.segments, true);
           if (Number.isFinite(currentFrame)) this.anim.goToAndStop(currentFrame, true);
           if (!wasPaused) this.anim.play();
@@ -264,7 +271,8 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
         ariaLabel = _this$props2.ariaLabel,
         isClickToPauseDisabled = _this$props2.isClickToPauseDisabled,
         title = _this$props2.title,
-        tabIndex = _this$props2.tabIndex;
+        tabIndex = _this$props2.tabIndex,
+        Container = _this$props2.as;
       var getSize = function getSize(initial) {
         var size;
         if (typeof initial === 'number') {
@@ -289,7 +297,7 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
         // Click-to-pause is intentional and role="button" is set; keyboard control
         // is not part of the API yet.
         // eslint-disable-next-line jsx-a11y/click-events-have-key-events
-        _react["default"].createElement("div", {
+        _react["default"].createElement(Container, {
           ref: function ref(c) {
             _this4.el = c;
           },
@@ -324,7 +332,8 @@ Lottie.propTypes = {
   isClickToPauseDisabled: _propTypes["default"].bool,
   title: _propTypes["default"].string,
   style: _propTypes["default"].object,
-  tabIndex: _propTypes["default"].number
+  tabIndex: _propTypes["default"].number,
+  as: _propTypes["default"].elementType
 };
 Lottie.defaultProps = {
   eventListeners: [],
@@ -337,5 +346,6 @@ Lottie.defaultProps = {
   ariaLabel: 'animation',
   isClickToPauseDisabled: false,
   title: '',
-  tabIndex: 0
+  tabIndex: 0,
+  as: 'div'
 };

package/package.json

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