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. This library is autolinking, so it connects to your app at runtime. 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, follow these instructions:

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

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

Reinstall package-lock.json file using the npm install command.
Add your Lottie animation to <app_package_root>/src/js/resources/. Add images for the 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")}
    />
  );
}

API reference

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 doesn’t support iOS, Android, and Windows-specific props.

Components

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 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 a 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`.	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 for 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 for when the animation loads. Only invoked once, when the animation asset loads.	None
`onAnimationJsonLoad`	No longer supported. Use `onAnimationLoad` instead.	None
`onAnimationPlay`	A callback for when the animation plays. Invoked every time you call `play()`.	None
`onAnimationPause`	A callback for when the animation pauses. Invoked every time you call `pause()`.	None
`onAnimationResume`	A callback for when the animation resumes. Invoked every time you call `resume()`.	None

Methods

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`	Resets the animation back to `0` progress.
`pause`	Pauses the animation.
`resume`	Resumes the paused animation.

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"
    }
  ]
}

Known issues and limitations

The following actions and APIs aren’t supported on Vega:

Passing a remote asset to ‘source’ with a URI
.lottie format assets
ColorFilters
TextFilterVega

Supported versions

Package name	Amazon NPM library version	Vega OS build number	Vega SDK version	Release notes
`@amazon-devices/react-native-gesture-handler`	2.0.0+2.13.0	`OS 1.1 (201010435950)`	0.19	Released as a system distributed library. Backward-compatibility checks are not required on the initial release.
`@amazon-devices/react-native-gesture-handler`	2.0.0+2.13.0	`OS 1.1 (201010438050)`	0.20

Supported Third-Party Libraries and Services.

​Installation

​Examples

​API reference

​Components

​Methods

​imageAssetsFolder usage

​Known issues and limitations

​Supported versions

​Related topics