react-lottie 2.3.2 → 2.4.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 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.4.0](https://github.com/chenqingspring/react-lottie/compare/v2.3.3...v2.4.0) (2026-11-08)
+
+### Features
+
+* apply `options.locationHref` before loading, so Safari keeps the masks, mattes, gradients and filters that lottie-web bakes into `url(#id)` references when the page uses a `<base>` tag or is served from a sub-path; changing it reloads the animation ([#111](https://github.com/chenqingspring/react-lottie/issues/111))
+* expose the container `margin` as a prop, accepting any CSS `margin` value or a number of pixels (default `0 auto`), applied before `style` so an explicit `style.margin` still wins ([#107](https://github.com/chenqingspring/react-lottie/issues/107))
+
+### Documentation
+
+* explain how to load animation data from a URL and why a URL belongs in `options.path`, not `animationData` ([#106](https://github.com/chenqingspring/react-lottie/issues/106))
+* explain the default click-to-pause behaviour and the `isClickToPauseDisabled` opt-out ([#110](https://github.com/chenqingspring/react-lottie/issues/110))
+* state that the `componentWill*` lifecycles deprecated in React 16.3 and removed in React 17 are not used ([#112](https://github.com/chenqingspring/react-lottie/issues/112), [#119](https://github.com/chenqingspring/react-lottie/issues/119))
+
+## [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,17 @@ 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.
+
+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
+calling were removed in 2.0.0, so React 17 and newer do not warn about legacy
+lifecycles or skip the data/`path` reload ([#77](https://github.com/chenqingspring/react-lottie/issues/77),
+[#119](https://github.com/chenqingspring/react-lottie/issues/119)).
 
 ## Local development
 
@@ -185,6 +194,53 @@ belongs in `options.path`; a namespace import
 (`import * as animationData`) is unwrapped automatically but the default import
 above is preferred.
 
+### Loading animation data from a URL
+
+Put the URL in `options.path`, not `options.animationData`. `animationData` is
+the parsed JSON object; lottie-web cannot fetch a string, so react-lottie throws
+an explanatory error if you pass one (issue #106):
+
+```jsx
+const defaultOptions = {
+  path: 'https://someurl.com/animationData.json',
+  loop: true,
+  autoplay: true,
+};
+
+<Lottie options={defaultOptions} width="1293px" height="300px" />
+```
+
+`path` accepts an absolute URL, a site-root path or a relative path. lottie-web
+fetches it after mount (nothing is requested during server rendering), and
+changing `path` reloads the animation. Because lottie-web owns the request,
+`colorFilters` is not applied — fetch the JSON yourself and pass the parsed
+object as `animationData` if you need to recolor it or send request headers:
+
+```jsx
+import { useEffect, useState } from 'react';
+
+function RemoteAnimation() {
+  const [animationData, setAnimationData] = useState(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    fetch('https://someurl.com/animationData.json')
+      .then((response) => response.json())
+      .then((data) => { if (!cancelled) setAnimationData(data); });
+    return () => { cancelled = true; };
+  }, []);
+
+  if (!animationData) return null;
+
+  return (
+    <Lottie options={{ animationData, loop: true, autoplay: true }} height={300} />
+  );
+}
+```
+
+See [Loading animation data without bloating the bundle](#loading-animation-data-without-bloating-the-bundle)
+for the bundle-size trade-offs between these approaches.
+
 ### Loading animation data without bloating the bundle
 
 A static import like `import animationData from './pinjump.json'` (the example
@@ -253,6 +309,216 @@ 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.
+
+### Masks are missing in Safari
+
+Safari resolves the `url(#…)` references that lottie-web generates for masks,
+mattes, gradients and filters against the document's base URL. When the page
+has a `<base href>` tag, or the animation is served from a path the browser
+resolves differently, those references point at the wrong document and Safari
+renders the animation without its masks. Chrome and Firefox usually still find
+them.
+
+lottie-web's documented workaround is to call `lottie.setLocationHref()` before
+the animation is generated. react-lottie exposes it as `options.locationHref`:
+
+```jsx
+const defaultOptions = {
+  animationData,
+  loop: true,
+  autoplay: true,
+  locationHref: window.location.href,
+};
+
+<Lottie options={defaultOptions} height={400} width={400} />
+```
+
+Pass the URL the page is actually served from, without the `#` fragment.
+lottie-web joins the value with `#<id>` when it builds the references, so a
+fragment produces broken URLs. The value is global to lottie-web, so pass the
+same `locationHref` to every `<Lottie />` on the page. Changing it regenerates
+the animation, because the base URL is baked into the generated markup.
+
+If you already import lottie-web yourself, calling the function directly works
+too, as long as the bundler resolves it to the same copy react-lottie uses:
+
+```js
+import lottie from 'lottie-web';
+
+lottie.setLocationHref(window.location.href);
+```
+
+Run that before the first animation mounts, for example at application startup.
+
+If the masks are still missing with the correct href, the artwork is the likely
+cause: complex masks and alpha mattes are the least reliable part of the SVG
+renderer. Compare with the [canvas renderer](#performance-on-ios-and-low-end-devices),
+or open the same JSON in lottie-web's own preview to confirm the problem is
+renderer-level rather than a react-lottie bug.
+
 ### Play on hover
 
 `eventListeners` takes lottie-web animation events (`complete`, `loopComplete`,
@@ -301,6 +567,33 @@ export default class HoverLottie extends React.Component {
 
 ```
 
+### Click to pause
+
+Clicking or tapping the animation pauses it, and clicking again resumes it.
+This is on by default: the container also has `ariaRole="button"`, so an
+animation that looks decorative is still an interactive control (issue
+[#110](https://github.com/chenqingspring/react-lottie/issues/110)).
+
+Disable it when the animation is decorative, or when you want a click to do
+something else:
+
+```jsx
+<Lottie options={defaultOptions} isClickToPauseDisabled />
+```
+
+The component has no `onClick` prop. Put your handler on a wrapper element
+instead; the click bubbles from the animation container to the wrapper:
+
+```jsx
+<div onClick={() => openDetails()}>
+  <Lottie options={defaultOptions} isClickToPauseDisabled />
+</div>
+```
+
+Without `isClickToPauseDisabled` both run: playback toggles and the wrapper's
+handler still fires after it. Leave the prop out when you want click-to-pause as
+well.
+
 ### Play a segment
 
 Pass `segments` to play a frame range instead of the whole animation. The
@@ -367,6 +660,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,9 +787,11 @@ 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* 
+>
+>**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).
 
 **colorFilters** *optional* [default: `[]`]
 
@@ -415,6 +806,17 @@ pixel value for containers width.
 
 pixel value for containers height.
 
+**margin** *optional* [default: `0 auto`]
+
+Margin of the container. Accepts any CSS `margin` value (`'20px'`,
+`'10px auto'`, `'1rem 2rem'`) or a number of pixels. Use it instead of
+`style.margin` when the default `0 auto` misbehaves in a browser (issue #107).
+`style` is merged after this prop, so an explicit `style.margin` still wins.
+
+```jsx
+<Lottie options={defaultOptions} margin="10px auto" />
+```
+
 **isStopped** *optional* [default: `false`]
 
 Stops the animation and resets it to the first frame. Setting it back to `false`
@@ -464,7 +866,11 @@ eventListeners=[
 ```
 
 **isClickToPauseDisabled** *optional* [default: `false`]
-When this props is left unspecified or is set to `false` animations are paused or resumed when a user clicks or taps them. If you do not want this behaviour set this prop to `true`.
+
+When this prop is left unspecified or is set to `false`, animations are paused
+or resumed when a user clicks or taps them. If you do not want this behaviour,
+set this prop to `true`. See [Click to pause](#click-to-pause) for a custom
+click handler.
 
 **ariaRole** *optional* [default: `button`]
 
@@ -481,8 +887,8 @@ Accessible name of the container.
 
 **style** *optional*
 
-Extra inline styles merged onto the container, after the `width`, `height` and
-layout defaults. Use it to override `overflow` or `margin`.
+Extra inline styles merged onto the container, after the `width`, `height`,
+`margin` and layout defaults. Use it to override `overflow`, for example.
 
 **tabIndex** *optional* [default: `0`]
 Tab order of the rendered container. Pass `-1` for a purely presentational
@@ -495,6 +901,50 @@ Element or component rendered as the animation container. Use `as="span"` when
 custom component must forward its `ref` to a DOM element. See
 [Render inline inside a paragraph](#render-inline-inside-a-paragraph).
 
+## Hooks and alternatives
+
+`react-lottie` is deliberately a thin class component over lottie-web. Its
+public API is the imperative instance on a `ref` (`play`, `pause`,
+`goToAndStop`, `goToAndPlay`, `playSegments`), so replacing the class with a
+hooks-only component would break every existing app without changing what is
+rendered. You do not need hooks to drive it declaratively, though: changing
+`options.animationData` or `options.path` reloads the animation, and changes to
+`segments`, `isPaused`, `isStopped`, `speed`, `direction` and `colorFilters`
+are applied to the running instance. A function component can hold the state
+around it (issue #117):
+
+```jsx
+import React, { useState } from 'react'
+import Lottie from 'react-lottie';
+import animationData from './pinjump.json'
+
+export default function Player() {
+  const [segment, setSegment] = useState([0, 30]);
+  const options = { animationData, loop: true };
+
+  return (
+    <div>
+      <Lottie options={options} segments={segment} width={240} height={240} />
+      <button onClick={() => setSegment([30, 60])}>next part</button>
+    </div>
+  );
+}
+```
+
+If you specifically want a hook-first API, use one of these wrappers instead:
+
+* [react-lottie-player](https://github.com/mifi/react-lottie-player) — the
+  `useLottie` hook, with `path` and `animationData` support (v2.1.0, last
+  published July 2024).
+* [lottie-react](https://github.com/Gamote/lottie-react) — actively
+  maintained, hooks-based API (v3.1.2).
+* [@lottiefiles/react-lottie-player](https://github.com/LottieFiles/lottie-react)
+  — LottieFiles' official wrapper, for LottieFiles-specific features
+  (v3.6.0).
+
+All of them wrap the same lottie-web runtime, so switching mostly changes the
+component API rather than how the animation is rendered.
+
 ## Related Projects
 
 * [lottie-web](https://github.com/airbnb/lottie-web) react-lottie is a wrapper of lottie-web

package/dist/index.js

@@ -100,6 +100,7 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
          whether either actually changed. */
       this.animationData = animationData;
       this.colorFilters = colorFilters;
+      this.locationHref = options.locationHref;
       var filteredAnimationData = (0, _colorFilters.applyColorFilters)(_normalizeAnimationData(animationData, options.path), colorFilters);
       this.options = {
         container: this.el,
@@ -117,6 +118,10 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
       if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production' && Array.isArray(colorFilters) && colorFilters.length > 0 && !animationData) {
         console.warn('[react-lottie] colorFilters requires options.animationData; ' + 'animations loaded from options.path are not recolored.');
       }
+
+      /* Must happen before the animation is generated: lottie-web bakes the base
+         URL into its mask, matte, gradient and filter references (issue #111). */
+      this.setLocationHref(options);
       this.anim = _lottieWeb["default"].loadAnimation(this.options);
       this.registerEvents(eventListeners);
       this.setSpeed();
@@ -151,10 +156,13 @@ 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);
+      /* 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;
       /* 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) {
+      if (dataChanged || pathChanged || colorFiltersChanged || locationHrefChanged || 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
@@ -165,11 +173,13 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
         this.destroy();
         this.animationData = this.props.options.animationData;
         this.colorFilters = this.props.colorFilters;
+        this.locationHref = this.props.options.locationHref;
         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)(_normalizeAnimationData(this.props.options.animationData, this.props.options.path), this.props.colorFilters);
+        this.setLocationHref(this.options);
         this.anim = _lottieWeb["default"].loadAnimation(this.options);
         this.registerEvents(this.props.eventListeners);
 
@@ -231,6 +241,22 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
     value: function setSubframe() {
       this.anim.setSubframe(this.props.isSubframe);
     }
+
+    /* lottie-web writes its internal mask, matte, gradient and filter references
+       as `url(<locationHref>#id)`. Safari resolves them against the page's base
+       URL, so a `<base href>` (or a mismatched asset URL) makes it drop the
+       masks; other browsers are more forgiving. lottie-web's documented fix is
+       the global `setLocationHref()`, which has to run before the animation is
+       generated (issue #111). Passing `options.locationHref` lets callers do
+       that without importing lottie-web themselves, which also works when the
+       bundler gives them a different copy of the player. */
+  }, {
+    key: "setLocationHref",
+    value: function setLocationHref(options) {
+      if (options.locationHref != null) {
+        _lottieWeb["default"].setLocationHref(options.locationHref);
+      }
+    }
   }, {
     key: "play",
     value: function play() {
@@ -303,6 +329,7 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
       var _this$props2 = this.props,
         width = _this$props2.width,
         height = _this$props2.height,
+        margin = _this$props2.margin,
         ariaRole = _this$props2.ariaRole,
         ariaLabel = _this$props2.ariaLabel,
         isClickToPauseDisabled = _this$props2.isClickToPauseDisabled,
@@ -322,7 +349,9 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
         width: getSize(width),
         height: getSize(height),
         overflow: 'hidden',
-        margin: '0 auto',
+        /* `margin` is a prop so callers do not have to fight the default through
+           `style` on browsers where centring with `0 auto` misbehaves (#107). */
+        margin: getSize(margin),
         outline: 'none'
       }, this.props.style);
       var onClickHandler = isClickToPauseDisabled ? function () {
@@ -357,6 +386,7 @@ Lottie.propTypes = {
   })),
   height: _propTypes["default"].oneOfType([_propTypes["default"].string, _propTypes["default"].number]),
   width: _propTypes["default"].oneOfType([_propTypes["default"].string, _propTypes["default"].number]),
+  margin: _propTypes["default"].oneOfType([_propTypes["default"].string, _propTypes["default"].number]),
   isStopped: _propTypes["default"].bool,
   isPaused: _propTypes["default"].bool,
   speed: _propTypes["default"].number,
@@ -383,5 +413,6 @@ Lottie.defaultProps = {
   isClickToPauseDisabled: false,
   title: '',
   tabIndex: 0,
-  as: 'div'
+  as: 'div',
+  margin: '0 auto'
 };

package/package.json

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