lottie-react-native

The @amazon-devices/lottie-react-native library extends Lottie React Native to support Lottie animations in React Native for Vega (RNK) apps. You can use this library in both TypeScript and JavaScript RNK projects to run Lottie animations.

You don't need to install this library separately, as it comes pre-installed with RNK apps. It functions as an autolinking library, connecting to your app at runtime. Remember that compatibility is only guaranteed between the library and its corresponding RNK version.

Amazon recommends updating the library version when you upgrade your RNK version. This practice helps maintain consistency and allows you to use the latest features and improvements.

Installation

To use the package, use the following instructions:

1. Add the JavaScript library dependency in your application's package.json:

   Copy code Copied to clipboard.

    "dependencies": {
         ...
         "@amazon-devices/lottie-react-native": "~2.0.0"
    }
   

2. Reinstall package-lock.json file using npm install command.
3. Add your Lottie animation to <app_package_root>/src/js/resources/. Add images for Lottie animation to <app_package_root>/assets/image/.

On Vega, you can place Lottie animations (not its image assets) in <app_package_root>/assets/raw/.

Examples

You can use Lottie in a declarative way, as shown in the following example.

Copy code Copied to clipboard.

import React from "react";
import LottieView from "@amazon-devices/lottie-react-native";

export default function Animation() {
  return (
    <LottieView source={require("../path/to/animation.json")} autoPlay loop />
  );
}

Alternatively, you can use this imperative API as shown in the following example.

Copy code Copied to clipboard.

import React, { useEffect, useRef } from "react";
import LottieView from "@amazon-devices/lottie-react-native";

export default function AnimationWithImperativeApi() {
  const animationRef = useRef<LottieView>(null);

  useEffect(() => {
    animationRef.current?.play();

    // Or set a specific startFrame and endFrame with:
    animationRef.current?.play(30, 120);
  }, []);

  return (
    <LottieView
      ref={animationRef}
      source={require("../path/to/animation.json")}
    />
  );
}

APIs

RNK uses lottie-react-native to add support for Lottie animations and supports the same APIs as lottie-react-native APIs.

The @amazon-devices/lottie-react-native library does not support iOS, Android, and Windows-specific props.

Component API

Methods (Imperative API)

As shown in the Examples, you can control the Lottie component in an imperative manner by capturing the component with React.useRef. The reference provides access to the methods listed below, which you can use to have more fine-grained control over your animation's behavior.

You can't invoke any of these methods when the animation is in the same state. For example, you can't invoke play() while the animation plays.

If you invoke play() with different parameters while the animation plays, the library uses the parameters passed in the most recent invocation.

Exceptions on Vega

The following actions and APIs are not supported on Vega:

• Passing a remote asset to 'source' with a URI
• .lottie format assets
• ColorFilters
• TextFilterVega

imageAssetsFolder usage

To use the imageAssetsFolder property in RNK, follow these steps:

1. Copy your image assets into [PROJECT FOLDER]/assets/image.
2. Create a lottie subfolder Create subfolders for each animation if needed.
3. In the imageAssetsFolder prop, refer to the folder using its relative path. For example: imageAssetsFolder={'lottie/animation_1'}.

By default, RNK provides [PROJECT FOLDER]/assets/image. You don't need to update imageAssetsFolder for images added directly to this folder.

For example, the following path doesn't require an imageAssetsFolder update: [PROJECT FOLDER]/assets/image/images/img_0.png.

The following example shows a JSON structure for reference.

Copy code Copied to clipboard.

{
  "assets": [
    {
      "id": "image_0",
      "w": 737,
      "h": 1215,
      "u": "images/",
      "p": "img_0.png"
    }
  ]
}

Supported versions

Related topics

• Supported Third-Party Libraries and Services.

Last updated: Sep 30, 2025