DOCSEARCHbyAlgolia
Submit Docs

react-lottie-player

repository·master·Indexed 19 days ago

https://github.com/mifi/react-lottie-player

A fully declarative React wrapper for lottie-web (version 2.1.0) that simplifies Lottie animation control. It handles prop changes for playback, speed, and segments while providing a hooks-based implementation to prevent memory leaks. The library supports loading animations via JSON animationData or URL paths, offers a LottiePlayerLight version to avoid using eval, and provides an imperative API via refs to access the underlying AnimationItem instance.

Tokens
1.6K
Snippets
8
Records
10
Agent score
68%

What's inside react-lottie-player

  3. Lazy load Lottie animations

    master

    To optimize performance, you can lazy load animations using one of three methods:

    Option 1: React code splitting (React.lazy)

    Wrap the Lottie component in a separate file and use React.lazy to import it.

    Option 2: Dynamic import with state

    Use useEffect to dynamically import the JSON data and store it in local state.

    Option 3: path URL

    Pass a direct URL to the path prop to let the player fetch the JSON automatically.

    // Option 1: React.lazy
import React from 'react';
const MyLottieAnimation = React.lazy(() => import('./MyLottieAnimation'));

export default function MyComponent() {
  return <MyLottieAnimation play />;
}

// Option 2: dynamic import with state
const Example = () => {
  const [animationData, setAnimationData] = useState<object>();

  useEffect(() => {
    import('./animation.json').then(setAnimationData);
  }, []);

  if (!animationData) return <div>Loading...</div>;
  return <Lottie animationData={animationData} />;
}

// Option 3: path URL
const Example = () => <Lottie path="https://example.com/lottie.json" />;

  5. Basic usage of the Lottie component

    master

    The Lottie component allows you to render animations using either animationData (a JSON object) or a path (a URL). It is fully declarative, meaning you can control playback via props like play and loop.

    import React from 'react'
import Lottie from 'react-lottie-player'
import lottieJson from './my-lottie.json'

export default function Example() {
  return (
    <Lottie
      loop
      animationData={lottieJson}
      play
      style={{ width: 150, height: 150 }}
    />
  )
}

  7. Use the Imperative API via ref

    master

    While the component is primarily declarative, you can access the underlying player instance using a ref. This allows you to access properties like currentFrame directly.

    const lottieRef = useRef();

useEffect(() => {
  console.log(lottieRef.current.currentFrame);
}, [])

return <Lottie ref={lottieRef} />;

  8. Configure the Lottie component with LottieProps

    master

    The Lottie component accepts LottieProps, which combines standard HTML div attributes with Lottie-specific configuration. You can load animations using either a path (URL string) or animationData (JSON object).

    <Lottie
  path="/animation.json"
  // OR
  animationData={animationData}
  play={true}
  loop={true}
/>

  9. Reference LottieProps configuration options

    master

    The following props are available for controlling the Lottie player:

    Animation Control

    • play: boolean - Controls whether the animation is playing.
    • speed: number - The playback speed.
    • direction: AnimationDirection - The direction of the animation.
    • loop: boolean - Whether the animation should loop.
    • goTo: number - The frame to jump to.
    • segments: AnimationSegment | AnimationSegment[] - Specific segments of the animation to play.
    • useSubframes: boolean - Whether to use subframes for smoother animation.

    Renderer Configuration

    • renderer: RendererType - The type of renderer to use (e.g., 'svg', 'canvas', 'html').
    • rendererSettings: object - Settings specific to the chosen renderer.
    • audioFactory: any - Factory for audio.

    Event Callbacks

    • onLoad: AnimationEventCallback - Triggered when the animation is loaded.
    • onComplete: AnimationEventCallback - Triggered when the animation finishes playing.
    • onLoopComplete: AnimationEventCallback - Triggered when a loop completes.
    • onEnterFrame: AnimationEventCallback - Triggered on every frame.
    • onSegmentStart: AnimationEventCallback - Triggered when a segment starts.

  10. Access the Lottie AnimationItem via ref

    master

    You can access the underlying Lottie AnimationItem instance by providing a ref to the Lottie component. This allows you to call imperative methods provided by the lottie-web library.

    import { useRef } from 'react';
import Lottie, { AnimationItem } from 'react-lottie-player';

const MyComponent = () => {
  const lottieRef = useRef<AnimationItem | undefined>(null);

  const handlePlay = () => {
    lottieRef.current?.play();
  };

  return <Lottie ref={lottieRef} path="/anim.json" />;
};