react-lottie 2.4.0 → 2.4.1

package/CHANGELOG.md

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

package/README.md

@@ -363,6 +363,35 @@ 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
@@ -473,6 +502,48 @@ 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 animation loads. Changing
+  `options.rendererSettings` on a mounted component does not re-apply it;
+  remount the animation (or change its `key`) to pick up a new value.
+
+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.
+
 ### Masks are missing in Safari
 
 Safari resolves the `url(#…)` references that lottie-web generates for masks,
@@ -581,6 +652,15 @@ something else:
 <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:
 
@@ -652,7 +732,7 @@ The container is a `div` by default, which is not a valid child of `<p>`. Pass
 
 ```jsx
 <p>
-  Text <Lottie as="span" options={defaultOptions} ariaRole="img" /> more text
+  Text <Lottie as="span" options={defaultOptions} ariaRole="img" tabIndex={-1} /> more text
 </p>
 ```
 
@@ -789,7 +869,7 @@ the object representing the animation settings that will be instantiated by body
 >
 >**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* 
+>**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 />`. Read once when the animation loads. 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).
 
@@ -892,7 +972,9 @@ Extra inline styles merged onto the container, after the `width`, `height`,
 
 **tabIndex** *optional* [default: `0`]
 Tab order of the rendered container. Pass `-1` for a purely presentational
-animation that should not receive keyboard focus.
+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`]
 

package/package.json

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