tessl/npm-lottie-react

React wrapper for Lottie animations providing Component and Hook APIs with interactivity support.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Interactivity API

Name: tessl/npm-lottie-react
Author: tessl

Advanced interactivity system for creating scroll-triggered and cursor-responsive Lottie animations with configurable actions and behaviors.

Capabilities

useLottieInteractivity Hook

Hook for adding scroll-based or cursor-based interactivity to Lottie animations, allowing animations to respond to user interactions.

/**
 * Hook for adding interactivity to Lottie animations
 * @param props - Interactivity configuration including lottie object, actions, and mode
 * @returns React element with interactivity applied
 */
function useLottieInteractivity(props: InteractivityProps): ReactElement;

interface InteractivityProps {
  /** Lottie object with View component and control methods */
  lottieObj: { View: ReactElement } & LottieRefCurrentProps;
  /** Array of actions to perform based on interactions */
  actions: Action[];
  /** Interaction mode: scroll-based or cursor-based */
  mode: "scroll" | "cursor";
}

Usage Examples:

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

// Scroll-based interactivity
const ScrollAnimation = () => {
  const lottieObj = useLottie({
    animationData,
    loop: false,
    autoplay: false,
  });

  const Animation = useLottieInteractivity({
    lottieObj,
    mode: "scroll",
    actions: [
      {
        type: "seek",
        frames: [0, 100],
        visibility: [0, 1] // Animate from 0% to 100% visibility
      }
    ]
  });

  return <div style={{ height: "200vh" }}>{Animation}</div>;
};

// Cursor-based interactivity
const CursorAnimation = () => {
  const lottieObj = useLottie({
    animationData,
    loop: false,
    autoplay: false,
  });

  const Animation = useLottieInteractivity({
    lottieObj,
    mode: "cursor",
    actions: [
      {
        type: "seek",
        frames: [0, 50],
        position: { x: [0, 1], y: [0, 1] }
      }
    ]
  });

  return (
    <div style={{ width: 400, height: 400, border: "1px solid #ccc" }}>
      {Animation}
    </div>
  );
};

// Multiple scroll actions
const MultiActionScroll = () => {
  const lottieObj = useLottie({
    animationData,
    loop: false,
    autoplay: false,
  });

  const Animation = useLottieInteractivity({
    lottieObj,
    mode: "scroll",
    actions: [
      {
        type: "play",
        frames: [0, 30],
        visibility: [0, 0.3]
      },
      {
        type: "seek",  
        frames: [30, 60],
        visibility: [0.3, 0.7]
      },
      {
        type: "loop",
        frames: [60, 90],
        visibility: [0.7, 1.0]
      }
    ]
  });

  return <div style={{ height: "300vh" }}>{Animation}</div>;
};

// Using with main Lottie component
import Lottie from "lottie-react";

const ComponentWithInteractivity = () => (
  <div style={{ height: "200vh" }}>
    <Lottie
      animationData={animationData}
      loop={false}
      autoplay={false}
      interactivity={{
        mode: "scroll",
        actions: [
          {
            type: "seek",
            frames: [0, 100],
            visibility: [0, 1]
          }
        ]
      }}
    />
  </div>
);

Action Types

Different types of actions that can be triggered by user interactions.

interface Action {
  /** Type of action to perform */
  type: "seek" | "play" | "stop" | "loop";
  /** Frame range for the action [startFrame, endFrame] */
  frames: [number] | [number, number];
  /** Visibility range for scroll mode [0-1, 0-1] (optional) */
  visibility?: [number, number];
  /** Position range for cursor mode (optional) */
  position?: Position;
}

interface Position {
  /** X-axis position range or exact position */
  x: number | [number, number];
  /** Y-axis position range or exact position */
  y: number | [number, number];
}

Action Type Details:

seek: Scrub through animation frames based on scroll position or cursor location
play: Start playing animation when conditions are met
stop: Stop animation at specific frame when conditions are met
loop: Loop specific frame range when conditions are met

Scroll Mode

Scroll-based interactivity where animations respond to page scroll position and element visibility.

// Scroll mode actions use visibility ranges
interface ScrollAction extends Action {
  /** Visibility percentage range [0-1, 0-1] where action is active */
  visibility: [number, number];
}

Scroll Mode Examples:

// Seek animation based on scroll position
{
  type: "seek",
  frames: [0, 120], // Animation frames 0-120
  visibility: [0, 1] // From 0% to 100% element visibility
}

// Play animation when element becomes 50% visible
{
  type: "play", 
  frames: [0, 60],
  visibility: [0.5, 1.0]
}

// Loop specific frames when element is fully visible
{
  type: "loop",
  frames: [60, 90],
  visibility: [0.8, 1.0]
}

// Stop at specific frame when scrolling up
{
  type: "stop",
  frames: [30],
  visibility: [0, 0.3]
}

Cursor Mode

Cursor-based interactivity where animations respond to mouse position within the animation container.

// Cursor mode actions use position ranges
interface CursorAction extends Action {
  /** Position ranges where action is active */
  position: Position;
}

interface Position {
  /** X-axis: exact position (number) or range ([min, max]) in 0-1 coordinates */
  x: number | [number, number];
  /** Y-axis: exact position (number) or range ([min, max]) in 0-1 coordinates */
  y: number | [number, number];
}

Cursor Mode Examples:

// Seek animation based on cursor position across entire container
{
  type: "seek",
  frames: [0, 100],
  position: { x: [0, 1], y: [0, 1] }
}

// Play animation in top-left quadrant
{
  type: "play",
  frames: [0, 50], 
  position: { x: [0, 0.5], y: [0, 0.5] }
}

// Loop animation when cursor is in center
{
  type: "loop",
  frames: [25, 75],
  position: { x: 0.5, y: 0.5 }
}

// Stop animation in bottom area
{
  type: "stop", 
  frames: [0],
  position: { x: [0, 1], y: [0.7, 1] }
}

Types

type InteractivityMode = "scroll" | "cursor";
type ActionType = "seek" | "play" | "stop" | "loop";
type Axis = "x" | "y";

interface InteractivityProps {
  lottieObj: { View: ReactElement } & LottieRefCurrentProps;
  actions: Action[];
  mode: InteractivityMode;
}

interface Action {
  type: ActionType;
  frames: [number] | [number, number];
  visibility?: [number, number];
  position?: Position;
}

interface Position {
  [key in Axis]: number | [number, number];
}