lottie-react-native - Amazon Vega Docs

The @amazon-devices/lottie-react-native library extends Lottie React Native to support Lottie animations in React Native for Vega (RNV) apps. You can use this library in both TypeScript and JavaScript RNV projects to run Lottie animations. You don’t need to install this library separately, as it comes pre-installed with RNV 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 RNV version. Amazon recommends updating the library version when you upgrade your RNV 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:

Add the JavaScript library dependency in the package.json file. Select the tab for your React Native version.

React Native 0.72
React Native 0.83

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

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

Reinstall package-lock.json file using npm install command.
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.

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.

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

RNV 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

Prop	Description	Default
`source`	Required - The source of animation. You can reference `source` as a local asset by a string, or remotely with an object with a `uri` property. You can also use an actual animation object, for example, `require('../path/to/animation.json')`.	None
`progress`	A number between 0 and 1, or an `Animated` number between 0 and 1. This number represents the normalized progress of the animation. If you update this prop, the animation updates to the frame at that progress value. This prop is optional if you are using the imperative API, which controls the component through a reference.	`0`
`speed`	A number between -1 and 1 representing the speed at which the animation progresses. Sending a negative value reverses the animation.	`1`
`duration`	The duration of the animation in milliseconds (ms). Takes precedence over `speed` when set. To use `duration`, use an actual JS object of an animation for `source`.	`undefined`
`loop`	A Boolean flag saying if the animation should loop.	`true`
`autoPlay`	A Boolean flag saying if the animation should start automatically when mounted. Use `autoplay` with the imperative API only, which controls the component through a reference.	`false`
`autoSize`	A Boolean flag saying if the animation should size itself automatically, according to the width in the animation’s JSON. To use `autoSize`, use an actual JS object of an animation for `source`.	`false`
`resizeMode`	Determines how to resize the animated view when the frame doesn’t match the raw image dimensions. Supports `cover`, `contain`, and `center`.	`contain`
`style`	Style attributes for the view, as expected in a standard View, aside from border styling `View`.	None
`imageAssetsFolder`	Required for Vega to work properly with assets. Some animations depend on other image assets. Use this folder path to house image assets needed for your Lottie animation	None
`onAnimationFinish`	A callback function called when the animation is finished. Called with a Boolean `isCancelled` argument, showing if the animation finished or cancelled. Called only when you set `loop` to false.	None
`onAnimationLoad`	A callback function called when the animation loads. Only invoked once, when the animation asset loads.	None
`onAnimationJsonLoad`	No longer supported. Use `onAnimationLoad`.	None
`onAnimationPlay`	A callback function called when the animation plays. Invoked every time you call `play()`.	None
`onAnimationPause`	A callback function called when the animation pauses. Invoked every time you call `pause()`.	None
`onAnimationResume`	A callback function called when the animation resumes. Invoked every time you call `resume()`.	None

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.

Method	Description
`play`	Completely plays the animation, at the speed specified as a prop. You can play a section of the animation when called as `play(startFrame, endFrame)`.
`reset`	Reset the animation back to `0` progress.
`pause`	Pauses the animation.
`resume`	Resumes the paused animation.

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
Test filter - there is no equivalent to TestFilterIos or TestFilterAndroid on Vega

imageAssetsFolder usage

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

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

By default, RNV 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.

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

Supported versions

NPM package version	Vega SDK version	Vega OS version	React Native version
~2.0.x+6.0.0-rc.1	0.23 and earlier	`OS 1.1 (1401010009820)` and earlier	0.72
~3.0.x+6.0.0-rc.1	0.24	`OS 1.2 (2101020054720)`	0.72, 0.83

Supported Third-Party Libraries and Services.

​Installation

​Examples

​APIs

​Component API

​Methods (Imperative API)

​Exceptions on Vega

​imageAssetsFolder usage

​Supported versions

​Related topics