or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

component-api.mdhook-api.mdindex.mdinteractivity-api.md
tile.json

tessl/npm-lottie-react

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/lottie-react@2.4.x

To install, run

npx @tessl/cli install tessl/npm-lottie-react@2.4.0

index.mddocs/

Lottie React

Lottie React is a React wrapper for Lottie animations that provides both declarative Component and Hook-based APIs. It wraps the lottie-web library to enable seamless integration of Adobe After Effects animations in React applications with full control over playback, styling, and interactivity.

Package Information

  • Package Name: lottie-react
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install lottie-react

Core Imports

import Lottie from "lottie-react";
import { useLottie, useLottieInteractivity, LottiePlayer } from "lottie-react";

// Type imports
import type { 
  LottieOptions, 
  LottieComponentProps, 
  LottieRefCurrentProps,
  InteractivityProps,
  Action
} from "lottie-react";

For CommonJS:

const Lottie = require("lottie-react").default;
const { useLottie, useLottieInteractivity, LottiePlayer } = require("lottie-react");

Basic Usage

import React from "react";
import Lottie from "lottie-react";
import animationData from "./animation.json";

// Basic component usage
const AnimationComponent = () => (
  <Lottie 
    animationData={animationData} 
    loop={true}
    autoplay={true}
    style={{ width: 300, height: 300 }}
  />
);

// Hook-based usage for programmatic control
import { useLottie } from "lottie-react";

const HookBasedAnimation = () => {
  const { View, play, pause, stop } = useLottie({
    animationData,
    loop: true,
    autoplay: false,
  });

  return (
    <div>
      {View}
      <button onClick={play}>Play</button>
      <button onClick={pause}>Pause</button>
      <button onClick={stop}>Stop</button>
    </div>
  );
};

Architecture

Lottie React is built around several key components:

  • Declarative Component API: Main Lottie component for simple use cases with props-based configuration
  • Hook-based API: useLottie hook providing programmatic control and React element output
  • Interactivity System: useLottieInteractivity for scroll and cursor-based animation control
  • Type Safety: Full TypeScript support with comprehensive type definitions
  • lottie-web Integration: Direct re-export of lottie-web's LottiePlayer for advanced use cases

Capabilities

Component API

Declarative React component for rendering Lottie animations with simple props-based configuration and optional interactivity features.

export default function Lottie(props: LottieComponentProps): ReactElement;

interface LottieComponentProps extends LottieOptions {
  interactivity?: Omit<InteractivityProps, "lottieObj">;
}

Component API

Hook API

Hook-based API providing programmatic control over Lottie animations with method returns for play, pause, stop, and other animation controls.

function useLottie<T extends RendererType = "svg">(
  props: LottieOptions<T>,
  style?: CSSProperties
): { View: ReactElement } & LottieRefCurrentProps;

Hook API

Interactivity API

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

function useLottieInteractivity(props: InteractivityProps): ReactElement;

interface InteractivityProps {
  lottieObj: { View: ReactElement } & LottieRefCurrentProps;
  actions: Action[];
  mode: "scroll" | "cursor";
}

Interactivity API

LottiePlayer Access

Direct access to the lottie-web player for advanced use cases requiring low-level animation control.

import { LottiePlayer } from "lottie-react";
// LottiePlayer is the lottie-web library re-exported for direct access

Core Types

interface LottieOptions<T extends RendererType = "svg"> extends 
  Omit<AnimationConfigWithData<T>, "container" | "animationData">, 
  Omit<React.HTMLProps<HTMLDivElement>, "loop"> {
  animationData: unknown;
  lottieRef?: LottieRef;
  onComplete?: AnimationEventCallback | null;
  onLoopComplete?: AnimationEventCallback | null;
  onEnterFrame?: AnimationEventCallback | null;
  onSegmentStart?: AnimationEventCallback | null;
  onConfigReady?: AnimationEventCallback | null;
  onDataReady?: AnimationEventCallback | null;
  onDataFailed?: AnimationEventCallback | null;
  onLoadedImages?: AnimationEventCallback | null;
  onDOMLoaded?: AnimationEventCallback | null;
  onDestroy?: AnimationEventCallback | null;
}

interface LottieRefCurrentProps {
  play: () => void;
  stop: () => void;
  pause: () => void;
  setSpeed: (speed: number) => void;
  goToAndStop: (value: number, isFrame?: boolean) => void;
  goToAndPlay: (value: number, isFrame?: boolean) => void;
  setDirection: (direction: AnimationDirection) => void;
  playSegments: (segments: AnimationSegment | AnimationSegment[], forceFlag?: boolean) => void;
  setSubframe: (useSubFrames: boolean) => void;
  getDuration: (inFrames?: boolean) => number | undefined;
  destroy: () => void;
  animationContainerRef: RefObject<HTMLDivElement>;
  animationLoaded: boolean;
  animationItem: AnimationItem | undefined;
}

type LottieRef = MutableRefObject<LottieRefCurrentProps | null>;

interface PartialLottieOptions extends Omit<LottieOptions, "animationData"> {
  animationData?: LottieOptions["animationData"];
}

interface PartialLottieComponentProps extends Omit<LottieComponentProps, "animationData"> {
  animationData?: LottieOptions["animationData"];
}

// Re-exported from lottie-web
type RendererType = "svg" | "canvas" | "html";
type AnimationDirection = 1 | -1;
type AnimationSegment = [number, number];