# Changelog

All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.

## [2.5.2](https://github.com/chenqingspring/react-lottie/compare/v2.5.1...v2.5.2) (2026-11-13)

### Bug Fixes

* apply a changed `options.loop` to the running animation instead of ignoring it until the next load: `false` now plays once and a number plays that many times even when set after mount, and the current frame and play/pause state are kept (a change used to be silently ignored)

### Documentation

* document changing `options.loop` on a mounted component, and correct the props table: `loop` and `autoplay` default to `true`, matching lottie-web
* Storybook demo `lottie-loop` with a live loop / play-once / repeat-count toggle and a restart button

## [2.5.1](https://github.com/chenqingspring/react-lottie/compare/v2.5.0...v2.5.1) (2026-11-13)

### Bug Fixes

* regenerate the animation when `options.renderer` changes, so a mounted component can switch between the `svg`, `canvas` and `html` engines and keeps its current frame and play/pause state; dropping the key falls back to `svg` (a change used to be silently ignored)

### Documentation

* document switching `options.renderer` on a mounted component, and that a light `lottie-web` build registers one renderer only
* Storybook demo `lottie-renderer` with a live `svg` / `canvas` toggle next to both engines on their own component

## [2.5.0](https://github.com/chenqingspring/react-lottie/compare/v2.4.2...v2.5.0) (2026-11-10)

### Features

* regenerate the animation when `options.rendererSettings` changes, so `preserveAspectRatio` and the other renderer settings can be switched on a mounted component; the current frame and play/pause state are kept, and recreating an equal object does not reload anything ([#98](https://github.com/chenqingspring/react-lottie/issues/98))
* Storybook demo of the live `preserveAspectRatio` toggle next to the three static modes

### Documentation

* document switching `rendererSettings` on a mounted component instead of remounting the animation ([#98](https://github.com/chenqingspring/react-lottie/issues/98))

## [2.4.2](https://github.com/chenqingspring/react-lottie/compare/v2.4.1...v2.4.2) (2026-11-09)

### Documentation

* state that there is no npm version requirement, and why 1.x printed an `Unsupported engine` warning with npm 6 and newer ([#87](https://github.com/chenqingspring/react-lottie/issues/87))

## [2.4.1](https://github.com/chenqingspring/react-lottie/compare/v2.4.0...v2.4.1) (2026-11-08)

### Documentation

* explain that `rendererSettings` belongs inside `options`, not on `<Lottie />`, and how `preserveAspectRatio` fits (`meet`), crops (`slice`) or stretches (`none`) an animation ([#98](https://github.com/chenqingspring/react-lottie/issues/98))
* explain why an embedded base64 image can raise `Invalid or unexpected token` from an `eval` inside a lottie expression, and how to find the offending expression ([#88](https://github.com/chenqingspring/react-lottie/issues/88))
* document taking a presentational animation out of the tab order and exposing it to screen readers with `tabIndex`, `ariaRole` and `ariaLabel` ([#130](https://github.com/chenqingspring/react-lottie/issues/130))
* add a Storybook demo of the `preserveAspectRatio` modes on a square animation in a wide container

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

* accept a namespace import (`import * as animationData`) by unwrapping its `default` export and clone frozen animation objects before handing them to lottie-web, so they no longer fail with `Cannot read property 'length' of undefined` (#24, #65)
* throw an actionable error when `options.animationData` is a string or when neither `animationData` nor `path` is provided, instead of lottie-web's `Cannot create property 'tf' on string` / `Cannot read property 'length' of undefined` deep in the renderer (#44)
* fix the README examples that read `.default` from a default import, which passed `undefined` as the animation data

## [2.3.1](https://github.com/chenqingspring/react-lottie/compare/v2.3.0...v2.3.1) (2026-11-05)

### Bug Fixes

* tolerate a missing or non-array `eventListeners` prop instead of throwing `eventListeners.forEach is not a function` on mount and unmount, which could break animations rendered through `React.lazy` ([#137](https://github.com/chenqingspring/react-lottie/issues/137))

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

* add a `colorFilters` prop that replaces the colors of fills, strokes and solid layers by keypath, mirroring lottie-react-native's API. The filters are applied to a copy of `animationData`; changing them reloads the animation while preserving the current frame and playback state ([#144](https://github.com/chenqingspring/react-lottie/issues/144))

## [2.1.0](https://github.com/chenqingspring/react-lottie/compare/v2.0.1...v2.1.0) (2026-11-05)

### Features

* add an `isSubframe` prop that is passed to lottie-web's `setSubframe()`, so `enterFrame` can fire only on whole After Effects frames, e.g. to trigger audio exactly on frame boundaries ([#71](https://github.com/chenqingspring/react-lottie/issues/71))
* expose `goToAndStop(frame, isFrame)` and `goToAndPlay(frame, isFrame)` on the component instance, which makes it possible to drive an animation from scroll position or jump to an exact frame/marker through a `ref` ([#40](https://github.com/chenqingspring/react-lottie/issues/40))

### Bug Fixes

* keep a playing animation running when an unrelated prop changes; added a regression test for the state-change pause reported in [#43](https://github.com/chenqingspring/react-lottie/issues/43)

## [2.0.1](https://github.com/chenqingspring/react-lottie/compare/v2.0.0...v2.0.1) (2026-11-05)

### Bug Fixes

* apply the `segments` prop on mount, so an animation starts inside the requested range instead of playing the full timeline until the prop changes; an animation created with `autoplay: false` stays paused at the start of the range

## [2.0.0](https://github.com/chenqingspring/react-lottie/compare/v1.2.10...v2.0.0) (2026-11-04)

This release folds in the changes that were prepared as 1.2.11 (never
published) and modernizes the development toolchain.

### Breaking Changes

* the `react` peer dependency is now `>=16.8.0` (previously `>=15.0.0`);
  React 15 is no longer supported. The component is tested against React 18
  and works with React 19.
* import animation JSON with a default import
  (`import animationData from './pinjump.json'`). A namespace import
  (`import * as animationData`) yields a frozen ESM module object that
  lottie-web cannot annotate, which fails under Vite and other strict ESM
  bundlers.

### Features

* add a `tabIndex` prop so presentational animations can be removed from the tab order ([#130](https://github.com/chenqingspring/react-lottie/issues/130))
* support the `renderer` option and document it in the README
* print a highlighted maintenance banner after `npm install` (maintained automatically by Relay; report bugs and feature requests on GitHub; https://get-relay.cc) and document it in the README

### Bug Fixes

* leave playback alone on re-renders unless a playback prop changed, so an `autoplay: false` animation no longer starts itself and a paused one is not restarted; a re-created but equal `segments` array no longer replays the animation ([#32](https://github.com/chenqingspring/react-lottie/issues/32), [#43](https://github.com/chenqingspring/react-lottie/issues/43))
* apply the initial `isStopped`, `isPaused` and `direction` props on mount instead of only on update
* replay changed segments immediately by passing `force` to `playSegments` ([#82](https://github.com/chenqingspring/react-lottie/issues/82))
* reload the animation when the remote `path` option changes ([#99](https://github.com/chenqingspring/react-lottie/issues/99))
* run the data/path reload on modern React instead of the deprecated `componentWillUpdate` ([#77](https://github.com/chenqingspring/react-lottie/issues/77))
* guard `destroy()` when the animation was never created ([#51](https://github.com/chenqingspring/react-lottie/issues/51))
* make the imperative `pause()` method actually pause, and stop restarting a paused animation on unrelated prop updates ([#58](https://github.com/chenqingspring/react-lottie/issues/58))
* drop the runtime dependency on `babel-runtime`, which broke consumers' builds ([#177](https://github.com/chenqingspring/react-lottie/issues/177))

### [1.2.10](https://github.com/chenqingspring/react-lottie/compare/v1.2.9...v1.2.10) (2024-11-30)


### Bug Fixes

* add babel-runtime ([eb089a4](https://github.com/chenqingspring/react-lottie/commit/eb089a4335a85a2996159762c8860673bf45b547))

### [1.2.9](https://github.com/chenqingspring/react-lottie/compare/v1.2.8...v1.2.9) (2024-11-22)

### [1.2.8](https://github.com/chenqingspring/react-lottie/compare/v1.2.7...v1.2.8) (2024-11-20)

### [1.2.7](https://github.com/chenqingspring/react-lottie/compare/v1.2.6...v1.2.7) (2024-11-16)


### Bug Fixes

* repository.url ([4093792](https://github.com/chenqingspring/react-lottie/commit/409379290c78fd9ef4e029b689e0a7028e9bb67d))

### [1.2.6](https://github.com/chenqingspring/react-lottie/compare/v1.2.5...v1.2.6) (2024-11-16)


### Features

* update lottie-web to latest ([8018d02](https://github.com/chenqingspring/react-lottie/commit/8018d02c0c5a42b315d3f1e3e4d2edb9572e5d46))

<a name="1.2.5"></a>
## [1.2.5](https://github.com/chenqingspring/react-lottie/compare/v1.2.4...v1.2.5) (2024-11-16)



<a name="1.2.4"></a>
## [1.2.4](https://github.com/chenqingspring/react-lottie/compare/v1.2.3...v1.2.4) (2024-01-04)



<a name="1.2.3"></a>
## [1.2.3](https://github.com/chenqingspring/react-lottie/compare/v1.2.2...v1.2.3) (2018-06-14)



<a name="1.2.2"></a>
## [1.2.2](https://github.com/chenqingspring/react-lottie/compare/v1.2.1...v1.2.2) (2018-06-14)



<a name="1.2.1"></a>
## [1.2.1](https://github.com/chenqingspring/react-lottie/compare/v1.2.0...v1.2.1) (2018-06-14)



<a name="1.2.0"></a>
# [1.2.0](https://github.com/chenqingspring/react-lottie/compare/v1.1.0...v1.2.0) (2018-06-14)


### Features

* Allow custom styles (helps fix [#18](https://github.com/chenqingspring/react-lottie/issues/18)) ([d624a51](https://github.com/chenqingspring/react-lottie/commit/d624a51))



<a name="1.1.0"></a>
# [1.1.0](https://github.com/chenqingspring/react-lottie/compare/v1.0.0...v1.1.0) (2018-04-03)



<a name="1.0.0"></a>
# [1.0.0](https://github.com/chenqingspring/react-lottie/compare/v0.2.5...v1.0.0) (2018-01-17)



<a name="0.2.5"></a>
## [0.2.5](https://github.com/chenqingspring/react-lottie/compare/v0.2.4...v0.2.5) (2017-12-12)



<a name="0.2.4"></a>
## [0.2.4](https://github.com/chenqingspring/react-lottie/compare/v0.2.3...v0.2.4) (2017-11-08)



<a name="0.2.3"></a>
## [0.2.3](https://github.com/chenqingspring/react-lottie/compare/v0.2.2...v0.2.3) (2017-11-06)



<a name="0.2.2"></a>
## [0.2.2](https://github.com/chenqingspring/react-lottie/compare/v0.2.1...v0.2.2) (2017-10-14)



<a name="0.2.1"></a>
## [0.2.1](https://github.com/chenqingspring/react-lottie/compare/v0.2.0...v0.2.1) (2017-08-21)



<a name="0.2.0"></a>
# [0.2.0](https://github.com/chenqingspring/react-lottie/compare/v0.1.1...v0.2.0) (2017-08-21)



<a name="0.1.1"></a>
## [0.1.1](https://github.com/chenqingspring/react-lottie/compare/v0.1.0...v0.1.1) (2017-07-07)



<a name="0.1.0"></a>
# [0.1.0](https://github.com/chenqingspring/react-lottie/compare/v0.0.8...v0.1.0) (2017-06-27)



<a name="0.0.8"></a>
## [0.0.8](https://github.com/chenqingspring/react-lottie/compare/v0.0.7...v0.0.8) (2017-04-24)



<a name="0.0.7"></a>
## [0.0.7](https://github.com/chenqingspring/react-lottie/compare/v0.0.6...v0.0.7) (2017-04-24)



<a name="0.0.6"></a>
## [0.0.6](https://github.com/chenqingspring/react-lottie/compare/v0.0.5...v0.0.6) (2017-04-22)



<a name="0.0.5"></a>
## [0.0.5](https://github.com/chenqingspring/react-lottie/compare/v0.0.4...v0.0.5) (2017-04-22)



<a name="0.0.4"></a>
## 0.0.4 (2017-04-22)
