lottie-react

lottie-react wraps Airbnb’s lottie-web player in a React-friendly API, exposing both a drop-in <Lottie /> component and a useLottie()/useLottieInteractivity() hook pair for rendering complex After Effects animations exported as Lottie JSON in real time. It handles the animation lifecycle (mount, play, loop, destroy) as React state and refs so consumers don’t have to manage the underlying lottie-web instance imperatively.

The interactivity hook adds scroll- and cursor-driven playback control on top of the base player, making it a common choice for marketing sites and product UIs that want polished, designer-authored motion graphics without hand-rolling CSS or canvas animation code.

What You Get

• A <Lottie /> component for dropping a Lottie JSON animation into a React tree with minimal setup
• A useLottie() hook returning a renderable View plus imperative playback controls (play, pause, stop, setSpeed, segments)
• A useLottieInteractivity() hook for scroll-linked and cursor-linked animation playback
• Full TypeScript typings for animation options, refs, and event callbacks (onComplete, onLoopComplete, onDOMLoaded, etc.)
• Direct access to the underlying lottie-web AnimationItem via lottieRef for advanced imperative control

Common Use Cases

• Rendering designer-exported After Effects/Lottie animations (loaders, micro-interactions, hero illustrations) in a React marketing site
• Building scroll-driven storytelling sections where animation progress is tied to scroll position via useLottieInteractivity
• Adding interactive hover/cursor-reactive animations to buttons or cards using cursor-based interactivity mode
• Replacing GIF or video loaders with lightweight, resolution-independent vector animations in a React app

Under The Hood

Architecture - useLottie (src/hooks/useLottie.tsx) owns the animation lifecycle: it creates a lottie-web AnimationItem in a useEffect keyed on the container ref and animation data, attaches/detaches the various on* event listeners passed as props, and exposes both a View (a plain div ref target) and an imperative ref object mirroring lottie-web’s own API (play, pause, setSpeed, playSegments, etc.); useLottieInteractivity wraps a useLottie instance and adds scroll or cursor position tracking that maps to goToAndStop/segment playback calls.

Tech Stack - A thin TypeScript wrapper around lottie-web (the only runtime dependency) with React as a peer dependency; built with a standard TS build pipeline and tested via src/__tests__ specs (Lottie.test.tsx, useLottie.test.tsx, useLottieInteractivity.test.tsx) using React Testing Library-style component/hook tests with bundled animation JSON fixtures under __tests__/assets.

Code Quality - The hook-based design keeps state management idiomatic to React (refs, effects, state) rather than reaching for imperative DOM manipulation outside React’s lifecycle, and the presence of dedicated tests per hook/component is a good sign; a // TODO in useLottie.tsx around manually excluding non-DOM props from the spread rest object is an acknowledged rough edge rather than a hidden one.

API Design - Offering both a ready-made <Lottie /> component and lower-level hooks gives consumers a choice between minimal boilerplate and full control, and mirroring lottie-web’s own method names (play, setSpeed, goToAndPlay) on the returned ref keeps the API familiar to anyone who has used lottie-web directly, at the cost of the wrapper types needing to track a moving upstream API surface.