lottie-react-native/lottie-react-nativePublic

NotificationsYou must be signed in to change notification settings
Fork1.8k
Star17k

Lottie wrapper for React Native.

License

Apache-2.0 license

17k stars 1.8k forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 850 Commits
.github		.github
.vscode		.vscode
.yarn		.yarn
docs		docs
example		example
packages/core		packages/core
.gitattributes		.gitattributes
.gitignore		.gitignore
.yarnrc.yml		.yarnrc.yml
CHANGELOG.md		CHANGELOG.md
CODEOWNERS		CODEOWNERS
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MIGRATION-5-TO-6.md		MIGRATION-5-TO-6.md
README.md		README.md
book.json		book.json
package.json		package.json
yarn.lock		yarn.lock

Repository files navigation

Lottie React Native

Lottie component for React Native (iOS,Android, andWindows)

Lottie is an ecosystem of libraries for parsingAdobe After Effects animations exported as JSON withbodymovin and rendering them natively!

For the first time, designers can createand ship beautiful animations without an engineer painstakingly recreating it by hand.

Installing

Breaking Changes in v6!

We've made some significant updates in version 6 that may impact your current setup. To get all the details about these changes, check out themigration guide.

Stay informed to ensure a seamless transition to the latest version. Thank you!

iOS and Android

Installlottie-react-native (latest):

yarn add lottie-react-native

Go to your ios folder and run:

pod install

Web

Installlottie-react-native (latest):

yarn add lottie-react-native

Add dependencies for web players:

yarn add @lottiefiles/dotlottie-react

Windows (React Native >= 0.63)

Install the `lottie-react-native` npm package. (Click to expand)

Add the following to the end of your project file. For C# apps, this should come after anyMicrosoft.Windows.UI.Xaml.CSharp.targets includes. For C++ apps, it should come after anyMicrosoft.Cpp.targets includes.

<PropertyGroupLabel="LottieReactNativeProps">    <LottieReactNativeDir>$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), 'node_modules\lottie-react-native\package.json'))\node_modules\lottie-react-native</LottieReactNativeDir></PropertyGroup><ImportGroupLabel="LottieReactNativeTargets">    <ImportProject="$(LottieReactNativeDir)\src\windows\cppwinrt\PropertySheets\LottieGen.Auto.targets" /></ImportGroup>

Add the LottieReactNative.vcxproj file to your Visual Studio solution to ensure it takes part in the build.

For C# apps, you'll need to install the following packages through NuGet:

LottieGen.MsBuild
Microsoft.UI.Xaml
Win2D.uwp
Microsoft.Toolkit.Uwp.UI.Lottie
- This package is used for loading JSON dynamically. If you only need codegen animation, you can set<EnableLottieDynamicSource>false</EnableLottieDynamicSource> in your project file and omit this reference.

For C++ apps, you'll need these NuGet packages:

LottieGen.MsBuild
Microsoft.UI.Xaml

WinUI 2.6 (Microsoft.UI.Xaml 2.6.0) is required by default. Overriding this requires creating a Directory.Build.props file in your project root with a<WinUIVersion> property.

In your application code where you set up your React Native Windows PackageProviders list, add the LottieReactNative provider:

// C#PackageProviders.Add(newLottieReactNative.ReactPackageProvider(newAnimatedVisuals.LottieCodegenSourceProvider()));

// C++#include<winrt/LottieReactNative.h>#include<winrt/AnimatedVisuals.h>...PackageProviders().Append(winrt::LottieReactNative::ReactPackageProvider(winrt::AnimatedVisuals::LottieCodegenSourceProvider()));

Codegen animations are supported by adding LottieAnimation items to your project file. These will be compiled into your application and available at runtime by name. For example:

<!-- .vcxproj or .csproj--><ItemGroup>    <LottieAnimationInclude="Assets/Animations/MyAnimation.json"Name="MyAnimation" /></ItemGroup>

// js<LottieViewsource={"MyAnimation"}style={{width:"100%",height:"100%"}}/>

Codegen is available to both C# and C++ applications. Dynamic loading of JSON strings at runtime is currently only supported in C# applications.

Privacy (iOS)

Lottie iOS and Lottie React Native do not collect any data. We provide this notice to help you fill outApp Privacy Details. Both libraries provide privacy manifests (Lottie iOS's privacy manifest,Lottie React Native's privacy manifest) which can be included in your app and are available as bundle resources within the libraries by default.

Usage

Lottie can be used in a declarative way:

importReactfrom"react";importLottieViewfrom"lottie-react-native";exportdefaultfunctionAnimation(){return(<LottieViewsource={require("../path/to/animation.json")}style={{width:"100%",height:"100%"}}autoPlayloop/>);}

Additionally, there is an imperative API which is sometimes simpler.

importReact,{useEffect,useRef}from"react";importLottieViewfrom"lottie-react-native";exportdefaultfunctionAnimationWithImperativeApi(){constanimationRef=useRef<LottieView>(null);useEffect(()=>{animationRef.current?.play();// Or set a specific startFrame and endFrame with:animationRef.current?.play(30,120);},[]);return(<LottieViewref={animationRef}source={require("../path/to/animation.json")}style={{width:"100%",height:"100%"}}/>);}

Lottie's animation view can be controlled by either React Native Animated or Reanimated API.

importReact,{useEffect,useRef,Animated}from"react";import{Animated,Easing}from"react-native";importLottieViewfrom"lottie-react-native";constAnimatedLottieView=Animated.createAnimatedComponent(LottieView);exportdefaultfunctionControllingAnimationProgress(){constanimationProgress=useRef(newAnimated.Value(0));useEffect(()=>{Animated.timing(animationProgress.current,{toValue:1,duration:5000,easing:Easing.linear,useNativeDriver:false,}).start();},[]);return(<AnimatedLottieViewsource={require("../path/to/animation.json")}progress={animationProgress.current}style={{width:"100%",height:"100%"}}/>);}

Changing color of layers:

NOTE: This feature may not work properly on Android. We will try fix it soon.

importReactfrom"react";importLottieViewfrom"lottie-react-native";exportdefaultfunctionChangingColorOfLayers(){return(<LottieViewsource={require("../path/to/animation.json")}colorFilters={[{keypath:"button",color:"#F00000",},{keypath:"Sending Loader",color:"#F00000",},]}style={{width:"100%",height:"100%"}}autoPlayloop/>);}

If you want to use`.lottie` files

You need to modify yourmetro.config.js file accordingly by addinglottie extension to theassetExts array:

const{ getDefaultConfig, mergeConfig}=require("@react-native/metro-config");constdefaultConfig=getDefaultConfig(__dirname);/** * Metro configuration * https://facebook.github.io/metro/docs/configuration * *@type {import('metro-config').MetroConfig} */constconfig={resolver:{assetExts:[...defaultConfig.resolver.assetExts,"lottie"],},};module.exports=mergeConfig(getDefaultConfig(__dirname),config);

Setup jest for dotLottie files

Create a file in the following path__mocks__/lottieMock.js and add the following code:

module.exports="lottie-test-file-stub";

Then add the following to yourjest.config.js file:

module.exports={  ...moduleNameMapper:{    ...,'\\.(lottie)$':'<rootDir>/jest/__mocks__/lottieMock.js',},  ...}

API

You can find the full list of props and methods available in ourAPI document. These are the most common ones:

Prop	Description	Default
`source`	Mandatory - The source of animation. Can be referenced as a local asset by a string, or remotely with an object with a`uri` property, or it can be an actual JS object of an animation, obtained (for example) with something like`require('../path/to/animation.json')`.	None
`style`	Style attributes for the view, as expected in a standard`View`.	You need to set it manually. Refer to thispull request.
`loop`	A boolean flag indicating whether or not the animation should loop.	`true`
`autoPlay`	A boolean flag indicating whether or not the animation should start automatically when mounted. This only affects the imperative API.	`false`
`colorFilters`	An array of objects denoting layers by KeyPath and a new color filter value (as hex string).	`[]`

More...

Troubleshooting

Not all After Effects features are supported by Lottie. If you notice there are some layers or animations missing checkthis list to ensure they are supported.

When it comes to animations, please validate that your animation file is compliant with the standard (for example, that it doesn't have floating number in places that require integers). If you have an animation that is not working as expected, it is always recommended that you look at theLogcat output on Android and theconsole on iOS, as both ecosystems will have logs attached in case of an error that usually highlights what has gone wrong.

View more documentation, FAQ, help, examples, and more atairbnb.io/lottie