react-lottie 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 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.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

package/README.md

@@ -2,6 +2,8 @@
 
 [![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
 
@@ -31,10 +33,7 @@ Install through npm:
 npm install --save react-lottie
 ```
 
-> **Note:** react-lottie is maintained automatically by Relay. Learn more at
-> [get-relay.cc](https://get-relay.cc).
->
-> Found a bug or have a feature request? Open an issue on
+> **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.
 
@@ -188,6 +187,22 @@ 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.
 
+### 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:
 
@@ -235,6 +250,13 @@ values play in reverse at that rate.
 `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]`.

package/dist/index.js

@@ -78,6 +78,7 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
       this.registerEvents(eventListeners);
       this.setSpeed();
       this.setDirection();
+      this.setSubframe();
 
       /* Apply a segment passed on mount. The component otherwise only reacts to
          `segments` changes, so the animation used to play the whole timeline
@@ -132,6 +133,7 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
       }
       this.setSpeed();
       this.setDirection();
+      this.setSubframe();
     }
   }, {
     key: "componentWillUnmount",
@@ -151,11 +153,33 @@ var Lottie = exports["default"] = /*#__PURE__*/function (_React$Component) {
     value: function setDirection() {
       this.anim.setDirection(this.props.direction);
     }
+
+    /* `isSubframe` mirrors lottie-web's setSubframe(): with it enabled (the
+       default) frames are interpolated, with it disabled `enterFrame` fires only
+       on whole After Effects frames (issue #71). */
+  }, {
+    key: "setSubframe",
+    value: function setSubframe() {
+      this.anim.setSubframe(this.props.isSubframe);
+    }
   }, {
     key: "play",
     value: function play() {
       this.anim.play();
     }
+
+    /* Frame/marker control from a ref, e.g. to sync an animation to scroll.
+       `isFrame` false treats the value as a time in seconds (issue #40). */
+  }, {
+    key: "goToAndStop",
+    value: function goToAndStop(value, isFrame) {
+      this.anim.goToAndStop(value, isFrame);
+    }
+  }, {
+    key: "goToAndPlay",
+    value: function goToAndPlay(value, isFrame) {
+      this.anim.goToAndPlay(value, isFrame);
+    }
   }, {
     key: "playSegments",
     value: function playSegments() {
@@ -258,6 +282,7 @@ Lottie.propTypes = {
   speed: _propTypes["default"].number,
   segments: _propTypes["default"].arrayOf(_propTypes["default"].number),
   direction: _propTypes["default"].number,
+  isSubframe: _propTypes["default"].bool,
   ariaRole: _propTypes["default"].string,
   ariaLabel: _propTypes["default"].string,
   isClickToPauseDisabled: _propTypes["default"].bool,
@@ -270,6 +295,7 @@ Lottie.defaultProps = {
   isStopped: false,
   isPaused: false,
   speed: 1,
+  isSubframe: true,
   ariaRole: 'button',
   ariaLabel: 'animation',
   isClickToPauseDisabled: false,

package/package.json

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