lottie-reactReference
useLottie and the instance
The four hooks, the instance's members, and what the handle keeps.
frame 0, state loading
import { LottieDisplay, useLottie } from "lottie-react";import { useRef } from "react";export function LiveReadouts() { const frame = useRef<HTMLSpanElement>(null); const state = useRef<HTMLSpanElement>(null); const lottie = useLottie({ src: "/anim.json", autoplay: true, loop: true, subscriptions: { frame: ({ currentFrame }) => { if (frame.current) { frame.current.textContent = String(Math.round(currentFrame)); } }, newState: ({ state: next }) => { if (state.current) { state.current.textContent = next; } }, }, }); return ( <> <LottieDisplay lottie={lottie} /> <p> frame <span ref={frame}>0</span>, state <span ref={state}>loading</span> </p> </> );}The hooks
| Hook | Signature | What it is for |
|---|---|---|
useLottie | (options) => LottieInstance | Loads and drives an animation with the full engine. Options are the component's own props, minus the element ones. |
useLottieSvg | (options) => LottieInstance | The same with the svg engine: svg only, expressions kept. |
useLottieLight | (options) => LottieInstance | The same with the light engine: svg only, no expressions. |
useLottieInstance | (lottie?) => LottieInstance | The explicit argument, else the surrounding <Lottie>'s context; throws with neither. For components of yours that work inside or beside an animation. |
The instance
| Group | Members |
|---|---|
| values | state, error, speed, direction, loop, playableFrames, playableDuration |
| commands | reload, play, pause, stop, seek, playSegments, resetSegments, scrubStart, scrubTo, scrubEnd, setSpeed, setDirection, setLoop |
| events | subscribe |
| dom | setDisplayRef, setRootRef, root |
| hatch | animationItem, the raw lottie-web object, outside the semver promise |
The values are React state and re-render what reads them.
playableFrames is a count (the last frame is one less), both playable* values follow the active segment, and the current frame is only reachable through the frame subscription.
The setters accept a value or an updater function.
The handle
LottieHandle, what lottieRef hands back, is the instance minus the values, subscribe, and the three dom members: commands and the escape hatch.
The values are absent by design: they live on the instance the hook returns and useLottieInstance reaches, and subscriptions carries the signals.
Refs and handles carries the why, and the two working together.