Add the dependency to your project build.gradle file:
dependencies {
...
implementation "com.airbnb.android:lottie:$lottieVersion"
...
}
The latest version is:
You can build the sample app yourself or download it from the Play Store. The sample app includes some built in animations but also allows you to load an animation from internal storage or from a url.
LottieAnimationViewextends ImageView and is the default and simplest way to load a Lottie animation.LottieDrawablehas most of the same APIs as LottieAnimationView but you can use it on any View you want.LottieCompositionis the stateless model representation of an animation. This file is safe to cache for as long as you need and can be freely reused across drawables/views.LottieCompositionFactoryallows you to create a LottieComposition from a number of inputs. This is what thesetAnimation(...)APIs onLottieDrawableandLottieAnimationViewuse under the hood. The factory methods share the same cache with those classes as well.
Lottie can load animations from:
- A json animation in
src/main/res/raw. - A json file in
src/main/assets. - A zip file in
src/main/assets. See images docs for more info. - A dotLottie file in
src/main/assets. - A url to a json or zip file.
- A json string. The source can be from anything including your own network stack.
- An InputStream to either a json file or a zip file.
The simplest way to use it is with LottieAnimationView:
It is recommended to use lottie_rawRes because you can use static references to your animation through R instead of just using string names.
<com.airbnb.lottie.LottieAnimationView
android:id="@+id/animation_view"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
app:lottie_rawRes="@raw/hello_world"
// or
app:lottie_fileName="hello_world.json"
// Loop indefinitely
app:lottie_loop="true"
// Start playing as soon as the animation is loaded
app:lottie_autoPlay="true" />LottieAnimationView, LottieDrawable, and LottieCompositionFactory each has methods for the corresponding locations.
Note: to correctly load dark mode (-night) resources, make sure you pass Activity as a context where possible (instead of e.g. the application context). The Activity won't be leaked.
All Lottie animations are cached with a LRU cache by default. Default cache keys will be created for animations loaded from res/raw/ or assets/. Other APIs require setting a cache key.
If you fire multiple animation requests for the same animation in parallel such as a wishlist heart in a RecyclerView, subsequent requests will join the existing task so it only gets parsed once.
Lottie has some global configuration options. None are required by default but it can be used to:
- Use your own network stack instead of Lottie's built in one when loading animations from the network.
- Provide your own cache directories for animation fetched from the network instead of using Lottie's default one (
cacheDir/lottie_network_cache). - Enable systrace makers for debugging.
- Disable Lottie's network cache completely if you want to implement custom network fetcher-level caching strategy.
To set it up, somewhere during your application initialization, include:
Lottie.initialize(
LottieConfig.Builder()
.setEnableSystraceMarkers(true)
.setNetworkFetcher(...)
.setNetworkCacheDir(...)
.setEnableNetworkCache(false)
)You can control the animation or add listeners:
animationView.addAnimatorUpdateListener { animation ->
}
animationView.addAnimatorListener(...)
animationView.addPauseListener {
}
In the update listener callback:
animation.getAnimatedValue() will return the progress of the animation regardless of the currently set min/max frame [0,1].
animation.getAnimatedFraction() will return the progress of the animation taking into account the set min/max frame [minFrame,maxFrame].
Set a default failure listener that will be called if any of the setAnimation APIs fail for any reason. This can be used to replace the default behavior. The default behavior will log any network errors and rethrow all other exceptions.
If you are loading an animation from the network, errors may occur if your user has no internet. You can use this listener to retry the download or you can have it default to an error drawable with setFallbackResource(int). Unless you are using setAnimationFromUrl(String), errors are unexpected.
Set the listener to null to revert to the default behavior.
Although playAnimation() is sufficient for the vast majority of use cases, you can call setProgress(...) in the update callback for your own animator. This can be useful to tie an animation to something like a gesture, download progress, or scroll position.
// Custom animation speed or duration.
val animator = ValueAnimator.ofFloat(0f, 1f)
animator.addUpdateListener {
animationView.setProgress(animation.animatedValue)
}
animator.start()Lottie support advanced looping functionality that mirrors ValueAnimator. As such, you can call setRepeatMode(...) or setRepeatCount(...) as you would on a ValueAnimator
You can also enable looping from xml with lottie_loop="true"
You can loop a specific part of an animation by using setMinFrame, setMaxFrame, or setMinAndMaxFrame. There are multiple versions of each that take frame, progress (from 0.0 to 1.0) or a marker name (specified in After Effects).
Lottie converts all px values in After Effects to dps on device so that everything is rendered at the same size across devices. This means that instead of making an animation in After Effects that is 1920x1080, it should be more like 411x731px in After Effects which roughly corresponds to the dp screen size of most phones today.
However, if your animation isn't the perfect size, you have two options:
You can update properties dynamically at runtime. This can be used for a variety of purposes such as:
- Theming (day and night or arbitrary themes).
- Responding to events such as an error or a success.
- Animating a single part of an animation in response to an event.
- Responding to view sizes or other values not known at design time.
To understand how to change animation properties in Lottie, you should first understand how animation properties are stored in Lottie.
Animation properties are stored in a data tree that mimics the information hierarchy of After Effects. In After Effects a Composition is a collection of Layers that each have their own timelines. Layer objects have string names, and their contents can be an image, shape layers, fills, strokes, or just about anything that is drawable. Each object in After Effects has a name. Lottie can find these objects and properties by their name using a KeyPath.
To update a property at runtime, you need 3 things:
- KeyPath
- LottieProperty
- LottieValueCallback
A KeyPath is used to target a specific content or a set of contents that will be updated. A KeyPath is specified by a list of strings that correspond to the hierarchy of After Effects contents in the original animation.
KeyPaths can include the specific name of the contents or wildcards:
- Wildcard
*- Wildcards match any single content name in its position in the keypath.
- Globstar
**- Globstars match zero or more layers.
KeyPaths have the ability to store an internal reference to the content that they resolve to. When you create a new KeyPath object, it will be unresolved. LottieDrawable and LottieAnimationView has a resolveKeyPath() method that takes a KeyPath and returns a list of zero or more resolved KeyPaths that each resolve to a single piece of content and are internally resolved. This can be used to discover the structure of your animation if you don't know it. To do so, in a development environment, resolve new KeyPath("**") and log the returned list. However, you shouldn't use ** by itself with a ValueCallback because it will be applied to every single piece of content in your animation. If you resolve your KeyPaths and want to subsequently add a value callback, use the KeyPaths returned from that method because they will be internally resolved and won't have to do a tree walk to find the content again.
See the documentation for KeyPath for more information.
LottieProperty is an enumeration of properties that can be set. They correspond to the animatable value in After Effects and the available properties are listed above and in the documentation for LottieProperty
The ValueCallback is what gets called every time the animation is rendered. The callback provides:
- Start frame of the current keyframe.
- End frame of the current keyframe.
- Start value of the current keyframe.
- End value of the current keyframe.
- Progress from 0 to 1 in the current keyframe without any time interpolation.
- Progress in the current keyframe with the keyframe's interpolator applied.
- Progress in the overall animation from 0 to 1.
There are also some helper ValueCallback subclasses such as LottieStaticValueCallback that takes a single value of the correct type in its constructor and will always return that. Think of it as a fire and forget value. There is also a relative value callback that offsets the real animation value by a specified amount.
- LottieValueCallback: Either set a static value in the contructor or override getValue() to set the value on every frame.
- LottieRelativeTYPEValueCallback: Either set a static value in the constructor or override getOffset() to set a value taht will be applied as an offset to the actual animation value on each frame. TYPE is the same type as the LottieProperty parameter.
- LottieInterpolatedTYPEValue: Supply a start value, end value, and optional interpolator to have the value automatically interpolate across the entire animation. TYPE is the same type as the LottieProperty parameter.
animationView.addValueCallback(
KeyPath("Shape Layer", "Rectangle", "Fill"),
LottieProperty.COLOR,
{ Color.RED }
)animationView.addValueCallback(
KeyPath("Shape Layer", "Rectangle", "Fill"),
LottieProperty.COLOR,
{ if (it.overallProgress < 0.5) Color.GREEN else Color.RED }
)The following value can be modified:
| Transform | Layer | Fill | Stroke | Ellipse | Polystar | Repeater | Image | Text |
|---|---|---|---|---|---|---|---|---|
| TRANSFORM_ANCHOR_POINT | TRANSFORM_ANCHOR_POINT | COLOR | STROKE_COLOR | ELLIPSE_SIZE | POLYSTAR_POINTS | REPEATER_COPIES | IMAGE | COLOR |
| TRANSFORM_POSITION | TRANSFORM_POSITION | OPACITY | STROKE_WIDTH | POSITION | POLYSTAR_ROTATION | REPEATER_OFFSET | COLOR_FILTER | STROKE_COLOR |
| TRANSFORM_OPACITY | TRANSFORM_OPACITY | COLOR_FILTER | COLOR_FILTER | POSITION | TRANSFORM_ROTATION | STROKE_WIDTH | ||
| TRANSFORM_SCALE | TRANSFORM_SCALE | OPACITY | POLYSTAR_OUTER_RADIUS | TRANSFORM_START_OPACITY | TEXT_TRACKING | |||
| TRANSFORM_ROTATION | TRANSFORM_ROTATION | POLYSTAR_OUTER_ROUNDEDNESS | TRANSFORM_END_OPACITY | TEXT_SIZE | ||||
| TIME_REMAP (composition) | POLYSTAR_INNER_RADIUS | TYPEFACE | ||||||
| TEXT |
Compositions and precomps (composition layers) have an a time remap proprty. If you set a value callback for time remapping, you control the progress of a specific layer. To do so, return the desired time value in seconds from your value callback.
The only animatable property that doesn't map 1:1 to an After Effects property is the color filter property you can set on fill content. This can be used to set blend modes on layers. It will only apply to the color of that fill, not any overlapping content.
Lottie is designed to work with vector shapes. Although Lottie supports rendering images, there are disadvantages to using them:
- The files are an order of magnitude larger than their equivalent vector animation.
- They get pixelated when scaled.
- They add complexity to the animation. Instead of one file, you have the json file plus all of the images.
A common cause of images in Lottie files is that bodymovin exports Illustrator layers from After Effects as images. If you think this might be the case, follow the instructions here.
You can set Lottie images in three ways:
Put the images in a folder inside of src/assets and don't change the filenames of the images.
Then, tell Lottie to the assets folder where the images are stored by calling setImageAssetsFolder on LottieAnimationView or
LottieDrawable with the relative folder inside of assets or with the app:lottie_imageAssetsFolder attribute on your LottieAnimationView.
Again,make sure that the images that bodymovin exports are in that folder with their names unchanged (should be img_#).
Alternatively, you can create a zip file with your json and images together. Lottie can unzip and read the contents. This can be done for local files or from a url.
Sometimes, you don't have the images bundled with the device. You may do this to save space in your apk or if you downloaded the animation from the network. To handle this case, you can use dynamic properties with LottieProperty.IMAGE
Very small:
- ~1600 methods.
- 287kb uncompressed.
There are two ways to render After Effects animations:
- Export json with Bodymovin and play it with lottie-android.
- Export AndroidVectorDrawable xml with Bodymovin and play it using the Android SDK.
- Supports a much larger set of After Effects features. See supported features for a full list.
- Manually set progress to hook up an animation to a gesture, event, etc.
- Download animations from the network.
- Dynamic playback speed.
- Masks are anti-aliased.
- Dynamically change the color of a specific part of an animations
- Faster peformance due to the animation running on the RenderThread vs the main thread.
Masks and mattes on android have the larges performance hit. Their performance hit is also proportional to the intersection bounds of the masked/matted layer and the mask/matte so the smaller the mask/matte, the less of a performance hit there will be.
On Android, if you are using masks or mattes, there will be a several X performance improvement when using hardware acceleration.
For debugging purposes, Lottie can outline all masks and mattes in your animation. To do that, just call setOutlineMasksAndMattes(true) on your LottieAnimationView or LottieDrawable.
Lottie supports hardware acceleration but it is disabled out of the box. Read this article to learn more about hardware acceleration. It is disabled by default because it doesn't support anti-aliasing, stroke caps (pre-API 18), and a few other things. In addition, depending on the animation, they may actually be less performant. Read this article to understand why.
If you are having performance issues with your animation, make sure to read the performance docs first. There is more information about how to benchmark and determine if your animation would benefit from hardware acceleration there.
Merge paths are only supported on KitKat and above. There is also some performance overhead in using them because [Path.Op](https://developer.android.com/reference/android/graphics/Path.html#op(android.graphics.Path,%20android.graphics.Path.Op) can be slow. To prevent engineers from testing on new devices with merge paths enabled while shipping a broken experience to users on older phones, they are disabled by default. If your minSdk is >=19 then you can enable then with enableMergePathsForKitKatAndAbove()
The Lottie sample app has a real time render graph that can be enabled from the menu in the top right. It also has guidelines for 16.66 and 33.333ms per frame which represent the maximum render time to hit 60fps and 30fps respectively.
The Lottie sample app also has a bottom sheet with the time it took each layer to render. To access it, click the render graph in the control bar and then tap "View render times per layer".
If there are any layers that are particularly slow, try optimizing their shapes, eliminated masks, mattes, and merge paths where possible.
There may be times in which Lottie doesn't render your animation correctly. After effects has an enormous number of features, not all of which are supported by Lottie. If an animation doesn't look correct, run through the following steps before reporting an issue.
The Lottie for Android will automatically detect and report some errors. It doesn't catch everything but will catch many common cases. You can either call getWarnings() from your own code or open the animation in the Lottie sample app and see if warnings show up in the top right. If they do, tapping it will give you more information.
Check the supported features page on this site to see if you are using anything that isn't supported.
Try rendering individual parts of the animation to see which feature isn't rendering correctly. See if you can narrow it down to a specific combination of shapes and effects or anything more specific than "it doesn't look right". If the issue should be supported and isn't, file an issue on the appropriate lottie github page with a description and a zip of the aep file.
Merge paths are only available on KitKat and above so you must manually enable them using enableMergePathsForKitKatAndAbove()
Make sure you are using the latest version of Lottie.
Performance and memory testing was aided by YourKit which provides powerful performance and memory profiling tools for Java.