react-lottie 2.3.2 → 2.3.3

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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.3](https://github.com/chenqingspring/react-lottie/compare/v2.3.2...v2.3.3) (2026-11-08)
+
+### Documentation
+
+* document animations that reference raster images: the `assets` array, the `assetsPath` option and rewriting assets to bundler-hashed URLs ([#49](https://github.com/chenqingspring/react-lottie/issues/49), [#59](https://github.com/chenqingspring/react-lottie/issues/59))
+* document aliasing `lottie-web` to `lottie_light`, `lottie_light_canvas` or `lottie_light_html` to cut the bundled player by about 45% ([#79](https://github.com/chenqingspring/react-lottie/issues/79))
+* document server-side rendering and add a regression test that renders the component in a Node process without a DOM ([#17](https://github.com/chenqingspring/react-lottie/issues/17))
+
 ## [2.3.2](https://github.com/chenqingspring/react-lottie/compare/v2.3.1...v2.3.2) (2026-11-07)
 
 ### Bug Fixes

package/README.md

@@ -103,8 +103,10 @@ shares one React copy and tree-shakes lottie-web is smaller.
 
 ## Requirements
 
-React 16.8 or newer. The test suite runs against React 18; the component uses
-plain class components and works with React 19 as well.
+React 16.8 or newer, including React 17, React 18 and React 19. The
+`react: ">=16.8.0"` peer dependency resolves without `--legacy-peer-deps` or
+`--force`. The test suite runs against React 18; the component uses plain class
+components and works with React 17 and React 19 as well.
 
 ## Local development
 
@@ -253,6 +255,170 @@ 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.
 
+### Animations with raster images
+
+An After Effects export that contains bitmap layers references those files from
+the animation's `assets` array. Each entry carries a directory (`u`), a file name
+(`p`) and an embedded flag (`e`):
+
+```json
+{ "id": "image_0", "w": 720, "h": 720, "u": "images/", "p": "img_0.png", "e": 0 }
+```
+
+With `"e": 0` lottie-web loads the file separately and resolves `u + p` relative
+to the page, which breaks as soon as the app is served from a sub-path or
+navigates client-side. Set `options.assetsPath` to the directory where the
+images are deployed instead; react-lottie forwards unknown options to
+lottie-web:
+
+```jsx
+const defaultOptions = {
+  path: '/animations/cypher.json',
+  assetsPath: '/animations/images/', // trailing slash required
+  loop: true,
+  autoplay: true,
+};
+
+<Lottie options={defaultOptions} height={400} width={400} />
+```
+
+Copy the images next to the JSON in `public/animations/images/` so they are
+served as static files instead of being bundled. `assetsPath` works with both
+`path` and `animationData`, and it applies to every image in the animation.
+
+If you want the bundler to hash and inline the images, import them yourself and
+rewrite the asset entries before passing the data. Don't mutate the imported
+JSON in place when it is a frozen ESM object:
+
+```jsx
+import img0 from './images/img_0.png';
+import animationData from './cypher.json';
+
+const data = {
+  ...animationData,
+  assets: animationData.assets.map((asset) => (
+    asset.id === 'image_0' ? { ...asset, u: '', p: img0 } : asset
+  )),
+};
+
+<Lottie options={{ animationData: data, loop: true, autoplay: true }} />
+```
+
+`"e": 1` means the image is embedded in the JSON as a base64 data URI. That
+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.
+
+### Shrinking the lottie-web bundle
+
+react-lottie imports the full `lottie-web` player (299 kB minified, 611 kB
+unminified in lottie-web 5.13), which includes the expression engine and every
+renderer. If your animations don't use expressions and you only need one
+renderer, alias `lottie-web` to a smaller build; react-lottie keeps working
+because those builds expose the same `loadAnimation` API.
+
+Vite:
+
+```js
+// vite.config.js
+export default defineConfig({
+  resolve: {
+    alias: {
+      'lottie-web': 'lottie-web/build/player/lottie_light.js',
+    },
+  },
+});
+```
+
+webpack (Create React App, Next.js):
+
+```js
+// next.config.js
+module.exports = {
+  webpack(config) {
+    config.resolve.alias['lottie-web'] = require.resolve(
+      'lottie-web/build/player/lottie_light.js'
+    );
+    return config;
+  },
+};
+```
+
+The light builds are about 45% smaller (164 kB vs 299 kB minified):
+
+* `lottie_light.js` — SVG renderer only, no expressions; shapes and raster
+  images still work.
+* `lottie_light_canvas.js` — canvas renderer only, no expressions.
+* `lottie_light_html.js` — HTML renderer only, no expressions.
+
+Pick the build that matches `options.renderer`: `lottie_light` only registers
+the SVG renderer, so pass `renderer: 'svg'` (the default); use
+`lottie_light_canvas` with `renderer: 'canvas'`. Don't alias when an animation
+uses expressions or effects, because the light builds silently skip them.
+
+### Performance on iOS and low-end devices
+
+File size mostly affects how long an animation takes to download and parse, not
+its frame rate. Once playback starts, the cost of each frame comes from what the
+renderer has to draw: the number of layers and shapes, masks and mattes,
+expressions, effects, and the pixel size of the canvas. A multi-megabyte export
+is a good signal that there is a lot of that (issue #133).
+
+On iOS 14.5, Safari, Chrome and Firefox all run on WebKit, so they render at the
+same speed; measuring in Safari is representative. Phones are also much slower
+than a desktop, so an animation that is smooth on a laptop can drop frames on
+mobile.
+
+In rough order of impact:
+
+1. **Reduce the animation.** Remove hidden and unused layers, flatten
+   precompositions, simplify masks and mattes, drop expressions and effects, and
+   avoid embedded raster images. If one scene is still heavy, split it into
+   smaller files and play only the needed range with `segments`.
+2. **Draw it at the size it is displayed.** `width` and `height` set the
+   container size; rendering a 1200 px animation into a 300 px slot does more
+   work than necessary. With the canvas renderer, also cap the backing-store
+   resolution: at a device pixel ratio of 3, a 400 px canvas is rasterized at
+   1200 px unless you set `dpr`.
+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.
+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
+   `ref`, driven by an `IntersectionObserver`.
+
+```jsx
+const defaultOptions = {
+  animationData,
+  loop: true,
+  autoplay: true,
+  renderer: 'canvas',
+  rendererSettings: {
+    dpr: 1, // render at CSS resolution; use 2 for a sharper middle ground
+  },
+};
+
+<Lottie options={defaultOptions} height={300} width={300} />
+```
+
+For the default `svg` renderer, `rendererSettings.progressiveLoad` builds the
+layers over several frames instead of blocking on the first one. It does not
+wait for the element to scroll into view; pause off-screen animations yourself:
+
+```jsx
+// `visible` is kept up to date by an IntersectionObserver on a wrapper element.
+<Lottie
+  options={{ animationData, loop: true, autoplay: false, rendererSettings: { progressiveLoad: true } }}
+  isPaused={!visible}
+/>
+```
+
+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.
+
 ### Play on hover
 
 `eventListeners` takes lottie-web animation events (`complete`, `loopComplete`,
@@ -367,6 +533,102 @@ The container is a `div` by default, which is not a valid child of `<p>`. Pass
 lottie-web should render into. Changing `as` reloads the animation into the new
 element and keeps the current frame.
 
+### Switch between several animations
+
+Each `<Lottie>` owns one lottie-web instance, so an app can render two
+animations side by side or keep one animation per page. To choose which one is
+shown, keep the animation data in a map and pass the entry for the current page
+as `options.animationData` (issue #128):
+
+```jsx
+import homeData from './animations/home.json';
+import aboutData from './animations/about.json';
+
+const animations = { home: homeData, about: aboutData };
+
+const PageAnimation = ({ page }) => (
+  <Lottie
+    options={{
+      loop: true,
+      autoplay: true,
+      animationData: animations[page],
+    }}
+    height={300}
+    width={300}
+  />
+);
+```
+
+Changing `options.animationData` reloads the animation into the same container,
+so a `key` is not required. Keep the JSON modules stable: copying the data in
+`render` (`animationData: { ...animations[page] }`) hands the component a new
+object on every render and reloads the animation each time. If you do want to
+start over — to replay an intro, for example — give the component a `key` so
+React unmounts and remounts it:
+
+```jsx
+<Lottie key={page} options={{ ...defaultOptions, animationData: animations[page] }} />
+```
+
+Unmounting destroys the lottie-web instance, so only the visible page animates.
+When the files are large, load them with `options.path` and fetch the JSON for
+the next page ahead of time instead of shipping every animation in one bundle;
+see [Loading animation data without bloating the bundle](#loading-animation-data-without-bloating-the-bundle).
+
+### Server-side rendering
+
+`<Lottie />` renders only a sized container element on the server; lottie-web is
+imported but instantiated in `componentDidMount` only, so `renderToString` (and
+Next.js/Gatsby prerendering) works and the animation starts after hydration:
+
+```jsx
+// server output: <div style="width:400px;height:400px;..."></div>
+<Lottie options={defaultOptions} height={400} width={400} />
+```
+
+Importing the package outside a browser no longer throws
+`ReferenceError: window is not defined`; lottie-web guards its DOM access at
+module load. If your bundler still evaluates the player on the server, load the
+component without SSR:
+
+```jsx
+// Next.js
+import dynamic from 'next/dynamic';
+
+const Lottie = dynamic(() => import('react-lottie'), { ssr: false });
+```
+
+Animations loaded from `options.path` are fetched by lottie-web after mount, so
+nothing is requested during the server render. Avoid the hydration trap
+described in [Animations and page navigation](#animations-and-page-navigation)
+when the container is nested in a `<p>`.
+
+### Animations and page navigation
+
+react-lottie creates a lottie-web instance when the component mounts and calls
+`destroy()` on unmount, so client-side navigation is safe as long as the page
+really unmounts. A layout that renders every page at once (or keeps pages
+mounted when switching tabs) keeps every animation running; mount only the
+visible one.
+
+One non-obvious trap on SSR frameworks such as Gatsby or Next.js: the wrapper is
+a `div` by default, and a `div` inside a `p` is invalid HTML. The browser moves
+the `div` out of the paragraph while parsing the server-rendered page, React
+reports a hydration mismatch (`validateDOMNesting`), and the animation node ends
+up outside the page subtree. Navigating back and forth can then leave animation
+nodes behind. Render the animation with `as="span"` (issue #73) or move it
+outside the paragraph:
+
+```jsx
+<p>
+  Text <Lottie as="span" options={defaultOptions} /> more text
+</p>
+```
+
+If animations still accumulate, confirm that each page unmounts (React DevTools
+shows the component tree changing), and pause off-screen instances as described
+in [Performance on iOS and low-end devices](#performance-on-ios-and-low-end-devices).
+
 ### Imperative control
 
 A `ref` to the component exposes `play()`, `pause()`, `stop()`,
@@ -398,7 +660,7 @@ the object representing the animation settings that will be instantiated by body
 >
 >**path** *optional* — a URL (or path) to a JSON animation file. Mutually exclusive with `animationData`.
 >
->**renderer** *optional* [default: `svg`]
+>**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* 
 

package/package.json

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