Gamote/lottie-react v3.0.0

on GitHub

v3 is a rewrite of lottie-react: one component for the easy path, the whole engine when you need control, and only what you import ships.

What is new

• Only what you import ships. One file per module and sideEffects: false, with per-import budgets enforced by the build. Lottie alone is about 4.4 kB gzipped and useLottie about 3.4 kB, engine external.
• Three builds of the engine, three pairs. Lottie and useLottie on the full engine; LottieSvg and useLottieSvg on lottie_svg (svg only, expressions kept); LottieLight and useLottieLight on lottie_light (svg only, no expressions, no eval). Each pair reaches only its own engine, which the build measures.
• src fetches. A path or URL loads with loading and error overlays (LottieLoading, LottieError) and a reload(); a parsed object still works.
• Reactive props. loop, speed and direction reach the running engine without reloading; src is compared by content, so a re-render never rebuilds the animation.
• A real seek API. seek() by frame, marker, percent or seconds; playSegments() by ranges or a marker; a scrub gesture (scrubStart, scrubTo, scrubEnd); subscriptions for every playback change.
• A player. LottieControls is an accessible control bar with keyboard shortcuts and fullscreen, paid for only when imported.
• Interactions. LottieInteractions with lottieScrollScrub and lottieInView, reduced motion respected, and a contract for writing your own.
• Server rendering safe by construction, and the library's style defaults always lose to yours (zero-specificity rules in a cascade layer).
• React 18 and 19, both tested against the real versions in CI.

Breaking changes

The default export is gone (everything is named), autoplay and loop default to false, animationData becomes src, the ten on* event props become one subscriptions object, useLottie returns the instance instead of a rendered view, useLottieInteractivity is replaced by the interactions module, deep imports stop resolving, and the React peer range moves to 18.2 or newer.

Every v2 surface is mapped to its v3 home, one table per area, in the migration guide: https://lottiereact.com/docs/migration

Documentation

The site is new: https://lottiereact.com, with the v2 reference kept at https://lottiereact.com/docs/v2 for projects staying on 2.x.

Install

npm i lottie-react