# Lottie Animation View for React ([Angular](https://github.com/chenqingspring/ng-lottie), [Vue](https://github.com/chenqingspring/vue-lottie))

[![npm version](https://badge.fury.io/js/react-lottie.svg)](http://badge.fury.io/js/react-lottie)

> **This project is fully maintained automatically by [Relay](https://get-relay.cc).**

## Demo
https://chenqingspring.github.io/react-lottie

## Wrapper of lottie-web

[lottie-web](https://github.com/airbnb/lottie-web) (previously Bodymovin) is an [Adobe After Effects](http://www.adobe.com/products/aftereffects.html) plugin for exporting animations as JSON. It also provides the player that renders them as svg/canvas/html.

## Why Lottie?

#### Flexible After Effects features
We currently support solids, shape layers, masks, alpha mattes, trim paths, and dash patterns. And we’ll be adding new features on a regular basis.

#### Manipulate your animation any way you like
You can go forward, backward, and most importantly you can program your animation to respond to any interaction.

#### Small file sizes
Bundle vector animations within your app without having to worry about multiple dimensions or large file sizes. Alternatively, you can decouple animation files from your app’s code entirely by loading them from a JSON API.

[Learn more](http://airbnb.design/introducing-lottie/) › http://airbnb.design/lottie/

Looking for lottie files › https://www.lottiefiles.com/

## Installation

Install through npm:
```
npm install --save react-lottie
```

> **Note:** Found a bug or have a feature request? Open an issue on
> [GitHub](https://github.com/chenqingspring/react-lottie/issues) and Relay
> will review and fix it.

## Using from a CDN (no bundler)

The published `dist/index.js` is a CommonJS build for bundlers and npm
consumers. It uses `exports` and expects `react`, `prop-types` and `lottie-web`
to be resolvable, so loading that file with a plain `<script>` tag fails with
`Uncaught ReferenceError: exports is not defined`. The package does not ship a
UMD/browser global build.

To use react-lottie without a build step, load it as an ES module from a CDN
and map `react` to the same copy the page uses. [esm.sh](https://esm.sh)
supports `?external=react` for exactly this:

```html
<script type="importmap">
  {
    "imports": {
      "react": "https://esm.sh/react@18",
      "react-dom/client": "https://esm.sh/react-dom@18/client",
      "react-lottie": "https://esm.sh/react-lottie@2?external=react"
    }
  }
</script>
<script type="module">
  import React from 'react';
  import { createRoot } from 'react-dom/client';
  import Lottie from 'react-lottie';

  const options = {
    path: '/animations/pinjump.json',
    loop: true,
    autoplay: true,
  };

  createRoot(document.getElementById('root')).render(
    React.createElement(Lottie, { options, height: 400, width: 400 })
  );
</script>
```

Without a compiler for JSX, create elements with `React.createElement`, or add
`htm`/Babel. Keeping `react` in the import map gives the page one React
instance; a CDN build that bundles its own React (such as jsDelivr's `+esm`
output) produces two copies, which breaks context and hooks.

If you only need to play an animation and not the React wrapper, load
lottie-web directly and skip React entirely:

```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/bodymovin/5.12.2/lottie.min.js"></script>
<script>
  lottie.loadAnimation({
    container: document.getElementById('root'),
    path: '/animations/pinjump.json',
    renderer: 'svg',
    loop: true,
    autoplay: true,
  });
</script>
```

An ESM CDN build still downloads React, React DOM, lottie-web and react-lottie,
so it removes the build step but not the bytes. For production, a bundler that
shares one React copy and tree-shakes lottie-web is smaller.

## Requirements

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.

There is no npm version requirement. 1.x declared
`"engines": { "npm": "^3.0.0" }`, so npm 6 and newer printed an
`Unsupported engine` warning on install; that field was removed before 2.0.0
([#87](https://github.com/chenqingspring/react-lottie/issues/87)). Install with
any npm version that can resolve the React peer dependency.

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

Run the Storybook stories with `npm start` (port 9010) and the test suite with
`npm test`.

## TypeScript

Type definitions are maintained on DefinitelyTyped and track this package's
props. Install them alongside the package:

```
npm install --save-dev @types/react-lottie
```

TypeScript picks the declarations up automatically, so no import changes are
needed.

## Testing

`lottie-web` probes canvas support when it is imported, so a jsdom-based test
runner needs a canvas implementation before the component is loaded. With Jest
(the default for Create React App), add [`jest-canvas-mock`](https://github.com/hustcc/jest-canvas-mock)
to your setup file:

```javascript
import 'jest-canvas-mock';
```

## Usage

Import pinjump.json as animation data

```jsx
import React from 'react'
import Lottie from 'react-lottie';
import animationData from './pinjump.json'

export default class LottieControl extends React.Component {

  constructor(props) {
    super(props);
    this.state = {isStopped: false, isPaused: false};
  }

  render() {
    const buttonStyle = {
      display: 'block',
      margin: '10px auto'
    };

    const defaultOptions = {
      loop: true,
      autoplay: true, 
      animationData,
      rendererSettings: {
        preserveAspectRatio: 'xMidYMid slice'
      }
    };

    return <div>
      <Lottie options={defaultOptions}
              height={400}
              width={400}
              isStopped={this.state.isStopped}
              isPaused={this.state.isPaused}/>
      <button style={buttonStyle} onClick={() => this.setState({isStopped: true})}>stop</button>
      <button style={buttonStyle} onClick={() => this.setState({isStopped: false})}>play</button>
      <button style={buttonStyle} onClick={() => this.setState({isPaused: !this.state.isPaused})}>pause</button>
    </div>
  }
}

```

Pass the parsed animation object as `options.animationData`. A file path or URL
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
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.

### 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.

### `Invalid or unexpected token` with embedded images

Embedded base64 images do work: an asset with `"e": 1` and a `p` value that
starts with `data:image/png;base64,` is decoded like any other image, and the
layer only has to reference it through `refId`.

The `Uncaught SyntaxError: Invalid or unexpected token` thrown from
`eval (eval at initiateExpression ...)` is not about the image. It comes from an
**expression** inside the animation. lottie-web compiles expressions with
`eval` when the animation loads. Newer After Effects versions can save an
expression in an encoded `@JSXBIN@…` form, which lottie-web cannot parse, so
the `eval` throws while the layer's effects are prepared
(`IImageElement.prepareProperties`). The same error can appear in animations
with no images at all.

Fixes, in order of preference:

- Remove the expressions in After Effects, or bake them to keyframes
  (**Animation → Keyframe Assistant → Convert Expression to Keyframes**), then
  export again. The animation keeps looking the same without runtime
  evaluation.
- Keep the expression only if it is plain JavaScript, and make sure a Content
  Security Policy is not blocking `eval` (it needs `'unsafe-eval'`). Otherwise
  move that behaviour out of the animation.
- If the expression is not needed for playback, alias `lottie-web` to one of
  the [light builds](#shrinking-the-lottie-web-bundle): they have no expression
  engine and skip expressions instead of throwing. They skip the effect's
  behaviour too, so only do this when the visual result is acceptable.

### 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; 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
   `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.

### Fit or crop an animation (preserveAspectRatio)

The SVG that lottie-web generates has its own `viewBox`, and the browser scales
it to the container according to `preserveAspectRatio`. lottie-web's default is
`xMidYMid meet`, which letterboxes the animation. Use `xMidYMid slice` to fill
the container and crop the overflow instead, or `none` to stretch it.

`rendererSettings` belongs **inside `options`**, next to `animationData` or
`path`. A `rendererSettings` prop on `<Lottie />` itself is ignored, because the
component only forwards `options` to `lottie.loadAnimation()`:

```jsx
const defaultOptions = {
  animationData,
  loop: true,
  autoplay: true,
  rendererSettings: {
    preserveAspectRatio: 'xMidYMid slice',
  },
};

// A wide box for a square animation, so `slice` has something to crop.
<Lottie options={defaultOptions} height={200} width={400} />
```

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 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
(`import * as animationData`) is unwrapped for you, but any payload lottie-web
cannot read leaves it without a `viewBox`, so the attribute has nothing to
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,
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`,
`enterFrame`, ...), not DOM events. Registering `onMouseOver` or `onMouseLeave`
there will never fire. Put the DOM handlers on a wrapper element and drive the
component with props instead.

To play forward on hover and reverse from the current frame on leave, keep the
animation running and flip `direction`. `isStopped` resets the animation to its
first frame, so only use it once, to start from a known state.

```jsx
import React from 'react'
import Lottie from 'react-lottie';
import animationData from './pinjump.json'

export default class HoverLottie extends React.Component {

  constructor(props) {
    super(props);
    this.state = {isStopped: true, direction: 1};
  }

  render() {
    const defaultOptions = {
      loop: false,
      autoplay: false,
      animationData,
      rendererSettings: {
        preserveAspectRatio: 'xMidYMid slice'
      }
    };

    return <div
      onMouseEnter={() => this.setState({isStopped: false, direction: 1})}
      onMouseLeave={() => this.setState({direction: -1})}>
      <Lottie options={defaultOptions}
              height={100}
              width={100}
              isStopped={this.state.isStopped}
              direction={this.state.direction}
              isClickToPauseDisabled />
    </div>
  }
}

```

### 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 />
```

A decorative animation should also leave the tab order. Pair
`isClickToPauseDisabled` with `tabIndex={-1}` so keyboard users do not land on
an animation they cannot interact with (issue
[#130](https://github.com/chenqingspring/react-lottie/issues/130)):

```jsx
<Lottie options={defaultOptions} isClickToPauseDisabled tabIndex={-1} />
```

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
frames are the ones shown in After Effects / the lottie editor.

```jsx
<Lottie options={defaultOptions}
        height={400}
        width={400}
        segments={[45, 90]} />
```

Changing `segments` while the animation is running restarts playback from the
new `fromFrame`, so a single state value is enough to switch ranges:

```jsx
<Lottie options={defaultOptions} segments={this.state.segment} />
```

A segment also has to be reachable with `loop`/`autoplay` as usual: with
`loop: false` and `autoplay: false` the range only plays once you flip
`isStopped` or pass a new `segments` value.

### Play once or loop

`loop` belongs inside `options` and defaults to `true`, like lottie-web, so an
animation keeps repeating unless you say otherwise. `false` plays it once and a
number plays it that many times:

```jsx
const [loop, setLoop] = useState(false);

<Lottie options={{ animationData, autoplay: true, loop }} height={200} width={200} />
<button onClick={() => setLoop(!loop)}>toggle loop</button>
```

Changing `options.loop` on a mounted component takes effect immediately. The
animation is not reloaded, so it keeps its current frame and play state, and the
new value decides what happens at the end of the current pass — a running
animation can be allowed to loop, or stopped after it finishes once. To replay
an animation that already finished with `loop: false`, call
`goToAndPlay(0, true)` through a ref (see [Imperative control](#imperative-control)).

The Storybook story `lottie-loop` demonstrates the toggle.

### Recolor an animation

`colorFilters` replaces the colors of fills, strokes and solid layers named by
a keypath, so one animation file can follow a theme (issue #144):

```jsx
<Lottie
  options={defaultOptions}
  colorFilters={[
    { keypath: 'Pin 1.Shape 2.Fill 1', color: '#4f46e5' },
    { keypath: 'Background', color: 'rgb(15, 23, 42)' },
  ]}
/>
```

A keypath is the dot-separated name chain from the layer down to the fill,
stroke or solid, e.g. `layer.group.fill`. For a layer inside a precomposition,
the composition name can be included (`Precomp.InnerLayer.Shape.Fill 1`) or
omitted. `*` matches one level and `**` matches any number of levels; dots in
a name can be escaped with a backslash. Colors accept hex, `rgb()`/`rgba()`,
`hsl()`/`hsla()` and the basic CSS color names. Invalid filters are ignored.

The filters are applied to `options.animationData`. Changing them reloads the
animation, because lottie-web cannot recolor a loaded animation; the current
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" tabIndex={-1} /> 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.

### 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()`,
`playSegments()`, `goToAndStop(frame, isFrame)` and
`goToAndPlay(frame, isFrame)`, mirroring the lottie-web animation object. Use
`isFrame: true` for a frame number, or omit it to pass a time in seconds. This
is how you can sync an animation to scroll position (issue #40):

```jsx
const lottie = useRef(null);

const onScroll = (frame) => lottie.current.goToAndStop(frame, true);

<Lottie ref={lottie} options={defaultOptions} />
```

### props
The `<Lottie />` Component supports the following props:

**options** *required*

the object representing the animation settings that will be instantiated by bodymovin. Currently a subset of the bodymovin options are supported:

>**loop** *options* [default: `true`] — `true` loops forever, `false` plays once, a number plays that many times. Changing it on a mounted component takes effect without reloading the animation. See [Play once or loop](#play-once-or-loop).
>
>**autoplay** *options* [default: `true`] — whether playback starts as soon as the animation loads. Load-time only: use `isPaused`/`isStopped` to control a mounted animation.
>
>**animationData** *optional* — the exported animation data. Mutually exclusive with `path`.
>
>**path** *optional* — a URL (or path) to a JSON animation file. Mutually exclusive with `animationData`.
>
>**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 />`. 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).

**colorFilters** *optional* [default: `[]`]

Array of `{ keypath, color }` objects that replace the colors of fills,
strokes and solid layers. See [Recolor an animation](#recolor-an-animation).

**width** *optional* [default: `100%`]

pixel value for containers width.

**height** *optional* [default: `100%`]

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`
resumes playback. Unlike `isPaused`, this discards the current position.

**isPaused** *optional* [default: `false`]

Pauses the animation without losing its current frame. Setting it back to
`false` resumes from where it stopped.

**speed** *optional* [default: `1`]

Playback rate. `2` plays twice as fast, `0.5` at half speed, and negative
values play in reverse at that rate.

**direction** *optional* [default: `1`]

`1` plays forward, `-1` plays backward. Changing it keeps the current frame,
which is what you want for hover-in / hover-out effects.

**isSubframe** *optional* [default: `true`]

Passed to lottie-web's `setSubframe()`. When `true`, frames are interpolated
for smooth playback. Set it to `false` to make the `enterFrame` event fire only
on whole After Effects frames, for example to trigger audio exactly on frame
boundaries (issue #71).

**segments** *optional* [default: none]

`[fromFrame, toFrame]` to play only part of the animation, e.g. `[45, 90]`.
The range is applied as soon as the prop is set and re-applied whenever it
changes, so a new value starts playing that segment immediately even while the
animation is running. See [Play a segment](#play-a-segment).

**eventListeners** *optional* [default: `[]`]

This is an array of objects containing a `eventName` and `callback` function that will be registered as  eventlisteners on the animation object. refer to [bodymovin#events](https://github.com/bodymovin/bodymovin#events) where the mention using addEventListener, for a list of available custom events. These are lottie-web animation events, not DOM events: for `onMouseOver`, `onMouseLeave` and friends put the handler on a wrapping element, as shown in [Play on hover](#play-on-hover).

example:
```jsx
eventListeners=[
  {
    eventName: 'complete',
    callback: () => console.log('the animation completed:'),
  },
]
```

**isClickToPauseDisabled** *optional* [default: `false`]

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`]

Role of the rendered container. Pass `img` for a purely decorative animation
that is described by `ariaLabel`.

**ariaLabel** *optional* [default: `animation`]

Accessible name of the container.

**title** *optional* [default: `''`]

`title` attribute (native tooltip) of the container.

**style** *optional*

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
animation that should not receive keyboard focus (issue
[#130](https://github.com/chenqingspring/react-lottie/issues/130)); combine it
with `isClickToPauseDisabled` as shown in [Click to pause](#click-to-pause).

**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).

## 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
* [Angular Lottie](https://github.com/chenqingspring/ng-lottie) angular implementation
* [Vue Lottie](https://github.com/chenqingspring/vue-lottie) vue implementation
* [React Native Lottie](https://github.com/airbnb/lottie-react-native) react native implementation by airbnb
* [IOS Lottie](https://github.com/airbnb/lottie-ios) ios implementation by airbnb
* [Android Lottie](https://github.com/airbnb/lottie-android) android implementation by airbnb

## Contribution
Your contributions and suggestions are heartily welcome.

## License
MIT

