Lottie for React
Edit page
Components
Hooks
useLottieuseLottieInteractivityGetting StartedParamsReturnsExamples

useLottieInteractivity

Getting Started

Use this hook along with the useLottie hook to add animations synced with scroll and cursor

Also read official lottie reference for general, non-react solution.

import { useLottie, useLottieInteractivity } from "lottie-react";
import likeButton from "./likeButton.json";


const style = {
  height: 300,
  border: 3,
  borderStyle: "solid",
  borderRadius: 7,
};


const options = {
  animationData: likeButton,
};


const Example = () => {
  const lottieObj = useLottie(options, style);
  const Animation = useLottieInteractivity({
    lottieObj,
    mode: "scroll",
    actions: [
      {
        visibility: [0.4, 0.9],
        type: "seek",
        frames: [0, 38],
      },
    ],
  });


  return Animation;
};


export default Example;

Params

ParamTypeRequiredDefaultDescription
lottieObjobjectrequiredResult returned from the useLottie() hook
modestringrequiredEither "scroll" or "cursor". Event that will be synced with animation
actionsarrayrequiredArray of actions that will run in sequence (SEE BELOW)

actions is an array of objects that define how animation will be run based on the chosen mode. One action chains the next one.

An action object is defined as:

{
  frames: [number] | [number, number];
  type: "seek" | "play" | "stop" | "loop";
  visibility?: [number, number];
  position?: { [axis in "x" | "y"]: number | [number, number] };
}

frames

Animation frame range to play for the action.

Let's say full animation has 150 frames. To sync all 150 frames with one action, you would pass [0, 150]. To start animation from 50 frame and end at 120, you would pass [50, 120]. To freeze animation at 80 frame, you would pass [80].

type

Action type.

'play', 'stop', 'loop' are pretty self-explanatory. With 'seek' passed, lottie will play animation frame by frame as you scroll down the page (mode: "scroll") or move cursor around (mode: "cursor").

visibility

Viewport of the action (mode "scroll" only)

Each action has a start and end which is essentially a percentage for the height of the lottie container and is a value between 0 and 1. To start the action when animation is visible on the page, you would pass [0, 1]. To start lottie after 40% scrolled and end at 85% scrolled, you would pass [0.4, 0.85].

position

Cursor viewport (mode "cursor" only)

You can define how much of the viewport cursor movement will cover inside the animation element. To set cursor cover the entire animation element, you would pass { x: [0, 1], y: [0, 1]}. To set cursor outside of the element, you would pass { x: -1, y: -1 }.

Returns

React.Element

You only need to render the returned value.

Examples

Lottie scroll with offset

From 0 to 45% of the container the Lottie will be stopped, and from 45% to 100% of the container the Lottie will be synced with the scroll.

import { useLottie, useLottieInteractivity } from "lottie-react";
import likeButton from "./likeButton.json";


const options = {
  animationData: likeButton,
};


const Example = () => {
  const lottieObj = useLottie(options);
  const Animation = useLottieInteractivity({
    lottieObj,
    mode: "scroll",
    actions: [
      {
        visibility: [0, 0.45],
        type: "stop",
        frames: [0],
      },
      {
        visibility: [0.45, 1],
        type: "seek",
        frames: [0, 38],
      },
    ],
  });


  return Animation;
};


export default Example;

Scroll effect with offset and segment looping

In cases where you would like the animation to loop from a specific frame to a specific frame, you can add an additional object to actions in which you can specify the frames. In the example below, the Lottie loops frame 45 to 60 once 45% of the container is reached.

import { useLottie, useLottieInteractivity } from "lottie-react";
import robotAnimation from "./robotAnimation.json";


const options = {
  animationData: robotAnimation,
};


const Example = () => {
  const lottieObj = useLottie(options);
  const Animation = useLottieInteractivity({
    lottieObj,
    mode: "scroll",
    actions: [
      {
        visibility: [0, 0.2],
        type: "stop",
        frames: [0],
      },
      {
        visibility: [0.2, 0.45],
        type: "seek",
        frames: [0, 45],
      },
      {
        visibility: [0.45, 1.0],
        type: "loop",
        frames: [45, 60],
      },
    ],
  });


  return Animation;
};


export default Example;

Play segments on hover

When the cursor moves in to the container, the Lottie loops from frame 45 to 60 as long as cursor is inside the container. The stop action as shown below is so that the animation is stopped at the 45th frame when cursor is outside.

import { useLottie, useLottieInteractivity } from "lottie-react";
import robotAnimation from "./robotAnimation.json";


const style = {
  height: 300,
  border: 3,
  borderStyle: "solid",
  borderRadius: 7,
};


const options = {
  animationData: robotAnimation,
};


const PlaySegmentsOnHover = () => {
  const lottieObj = useLottie(options, style);
  const Animation = useLottieInteractivity({
    lottieObj,
    mode: "cursor",
    actions: [
      {
        position: { x: [0, 1], y: [0, 1] },
        type: "loop",
        frames: [45, 60],
      },
      {
        position: { x: -1, y: -1 },
        type: "stop",
        frames: [45],
      },
    ],
  });


  return Animation;
};


export default PlaySegmentsOnHover;

Sync cursor position with animation

Moving the cursor from top left of the container to the bottom right of the container completes the animation. The seeking of the animation is synced to the diagonal movement of the cursor.

import { useLottie, useLottieInteractivity } from "lottie-react";
import robotAnimation from "./robotAnimation.json";


const style = {
  height: 300,
  border: 3,
  borderStyle: "solid",
  borderRadius: 7,
};


const options = {
  animationData: robotAnimation,
};


const CursorDiagonalSync = () => {
  const lottieObj = useLottie(options, style);
  const Animation = useLottieInteractivity({
    lottieObj,
    mode: "cursor",
    actions: [
      {
        position: { x: [0, 1], y: [0, 1] },
        type: "seek",
        frames: [0, 180],
      },
    ],
  });


  return Animation;
};


export default CursorDiagonalSync;

Sync animation with cursor horizontal movement

Move your cursor on the animation below. You may interchange the x and y arrays to get the vertical movement of the cursor synced with the animation.

import { useLottie, useLottieInteractivity } from "lottie-react";
import hamsterAnimation from "./hamsterAnimation.json";


const style = {
  height: 300,
  border: 3,
  borderStyle: "solid",
  borderRadius: 7,
};


const options = {
  animationData: hamsterAnimation,
};


const CursorHorizontalSync = () => {
  const lottieObj = useLottie(options, style);
  const Animation = useLottieInteractivity({
    lottieObj,
    mode: "cursor",
    actions: [
      {
        position: { x: [0, 1], y: [-1, 2] },
        type: "seek",
        frames: [0, 179],
      },
      {
        position: { x: -1, y: -1 },
        type: "stop",
        frames: [0],
      },
    ],
  });


  return Animation;
};


export default CursorHorizontalSync;