react-lottie-hook

Lottie react hook with runtime animation controls.

codesandbox · storybook

Introduction

Lottie is a library for the Web, Android and iOS that parses Adobe After Effects animations through a plugin called bodymovin and exported as JSON; rendering natively on each platform.

Getting Started

Add it with your prefered package manager:

yarn add react-lottie-hook

npm i react-lottie-hook

Usage Instructions

This library main exports a useLottie hook and supplies also a standard Lottie component but you are not required to use the latter.

The useLottie hook requires a configuration object of type LottieConfig to be supplied to it and in return you will get an array with a ref to the animation container, state of the animation and the control actions, respectively.

import React from "react";
import { useLottie, Lottie } from "react-lottie-hook";
import animationData from "./animation.json";

const App = () => {
  const [lottieRef, { isPaused, isStopped }, controls] = useLottie({
    renderer: "svg",
    rendererSettings: {
      preserveAspectRatio: "xMidYMid slice",
      progressiveLoad: false,
    },
    animationData,
  });

  return <Lottie lottieRef={ref} width={400} height={400} />;
};

The exported Lottie component has a type of LottieProps and the minimum props it requires is a lottieRef from the useLottie hook.

Lottie Component props:

| props | type | default | | ---------- | ---------------------------------------------- | ------- | | lottieRef: | React.MutableRefObject<HTMLElement | null> | | | width? | number | 200px | | height? | number | 200px | | style? | object | | | title? | string | | | className? | string | | | ariaRole? | string | | | ariaLabel? | string | | | onKeyDown? | (e: React.KeyboardEvent) => void | | | onClick? | (e: React.MouseEvent<HTMLElement, MouseEvent>) | |

EventListeners:

Among the options you can pass useLottie is an eventListeners object as follows:

const eventListeners: EventLisener = {
  /** triggered only if loop is set to true */
  loopCompleted: (data) => { console.log('Animation Loop Completed'); },
  /** triggered when animation is destroyed */
  destroy: : (data) => { console.log('Animation Destroyed'); },
  /** triggered when loop is set to false */
  complete: (data) => { console.log('Animation Complete'); },
};

const [lottieRef, { isPaused, isStopped }, controls] = useLottie({
  renderer: "svg",
  loop: false, // default true
  rendererSettings: {
    preserveAspectRatio: "xMidYMid slice",
    progressiveLoad: false,
  },
  animationData,
  eventListeners,
});

Contributors