airbnb / lottie-ios

An iOS library to natively render After Effects vector animations

Lottie for iOS

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

Lottie is a cross-platform library for iOS, macOS, tvOS, visionOS, Android, and Web that natively renders vector-based animations and art in realtime with minimal code.

Lottie loads and renders animations and vectors exported in the bodymovin JSON format. Bodymovin JSON can be created and exported from After Effects with bodymovin, Sketch with Lottie Sketch Export, and from Haiku.

Designers can create and ship beautiful animations without an engineer painstakingly recreating them by hand. Since the animations are backed by JSON, they are extremely small in size but can be large in complexity! Animations can be played, resized, looped, sped up, slowed down, reversed, and even interactively scrubbed. Lottie can play or loop just a portion of the animation as well, the possibilities are endless! Animations can even be changed at runtime in various ways! Change the color, position, or any keyframable value!

Here is just a small sampling of the power of Lottie

Installing Lottie

Lottie supports Swift Package Manager, CocoaPods, and Carthage (Both dynamic and static).

Github Repo

You can pull the Lottie Github Repo and include the Lottie.xcodeproj to build a dynamic or static library.

Swift Package Manager

To install Lottie using Swift Package Manager you can follow the tutorial published by Apple using the URL for the Lottie repo with the current version:

1. In Xcode, select “File” → “Add Packages...”
2. Enter https://github.com/airbnb/lottie-spm.git

or you can add the following dependency to your Package.swift:

.package(url: "https://github.com/airbnb/lottie-spm.git", from: "4.4.3")

When using Swift Package Manager we recommend using the lottie-spm repo instead of the main lottie-ios repo. The main git repository for lottie-ios is somewhat large (300+ MB), and Swift Package Manager always downloads the full repository with all git history. The lottie-spm repo is much smaller (less than 500kb), so can be downloaded much more quickly.

Instead of downloading the full git history of Lottie and building it from source, the lottie-spm repo just contains a pointer to the precompiled XCFramework included in the latest lottie-ios release (typically ~8MB). If you prefer to include Lottie source directly your project, you can directly depend on the main lottie-ios repo by referencing https://github.com/airbnb/lottie-ios.git instead.

CocoaPods

Add the pod to your Podfile:

pod 'lottie-ios'

And then run:

pod install

After installing the cocoapod into your project import Lottie with

import Lottie

Carthage

Add Lottie to your Cartfile:

github "airbnb/lottie-ios" "master"

And then run:

carthage update

In your application targets “General” tab under the “Linked Frameworks and Libraries” section, drag and drop lottie-ios.framework from the Carthage/Build/iOS directory that carthage update produced.

Swift Version Support

Lottie supports Swift / Xcode versions back to the minimum version that is permited by Apple for submissions to the App Store. You can see the most up-to-date information for which Swift versions Lottie supports on Swift Package Index:

Privacy

Lottie does not collect any data. We provide this notice to help you fill out App Privacy Details. We additionally provide a privacy manifest which can be included in your app.

Security

We distribute XCFramework bundles for each release on GitHub. In Lottie 4.4.0 and later, these XCFramework bundles include a code signature. These bundles are self-signed under the name "Lottie iOS" and have the following fingerprint:

89 2F 1B 43 04 7B 50 53 8F 2F 46 EA D9 29 00 DD 3D 48 11 F358 21 78 C0 61 A5 FB 20 F1 11 CB 26

In Xcode you can verify this by selecting Lottie.xcframework and confirming that it shows the following information:

Contributing

We always appreciate contributions from the community. To make changes to the project, you can clone the repo and open Lottie.xcworkspace. This workspace includes:

• the Lottie framework (for iOS, macOS, and tvOS)
• unit tests and snapshot tests (for iOS, must be run on an iPhone 8 simulator)
• an Example iOS app that lets you browse and test over 100 sample animations included in the repo

All pull requests with new features or bug fixes that affect how animations render should include snapshot test cases that validate the included changes.

• To add a new sample animation to the snapshot testing suite, you can add the .json file to Tests/Samples. Re-run the snapshot tests to generate the new snapshot image files.
• To update existing snapshots after making changes, you can set isRecording = true in SnapshotTests.swift setUp() method and then re-run the snapshot tests.

The project also includes several helpful commands defined in our Rakefile. To use these, you need to install Bundler:

$ sudo gem install bundle
$ bundle install

For example, all Swift code should be formatted according to the Airbnb Swift Style Guide. After making changes, you can reformat the code automatically using SwiftFormat and SwiftLint by running bundle exec rake format:swift. Other helpful commands include:

$ bundle exec rake build:all # builds all targets for all platforms
$ bundle exec rake build:package:iOS # builds the Lottie package for iOS
$ bundle exec rake test:package # tests the Lottie package
$ bundle exec rake format:swift # reformat Swift code based on the Airbnb Swift Style Guide

lottie-ios's Issues

Classes should use a three letter prefix.

"Two-letter prefixes... are reserved by Apple for use in framework classes."
https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Conventions/Conventions.html

Consider changing LA -> LOT to avoid namespace collisions.

Not all development environments support paths with spaces

Looks like a recent update added folders with spaces. Not all development environments support that. You might want to consider camel-casing instead.

Lottie Swift Support.

When I try to download Lottie with Carthage for Swift it gives me an error that it can't run the Objective-C module Lottie.

Add the ability to use Xcode playgrounds

Add the ability to use Xcode playgrounds.

thx

Support Even-Odd Fill Rule

Archive.zip

pod 安装失败

[!] Unable to find a specification for lottie-ios

Can't get simple animation to work

Made a simple animation with a square and it's not working at all, see attached files.
Using AE CC 2017
I added the json file to the iOS project and ran it on my device.
Works & looks just fine in the html doc.

Archive.zip

How to add it without pod or Carthage

How can I use it? I want to just add some files to use it. thanks for help

The animation doesn't works but only shows the background layer

I render the comp and get the json,everything looks fine,but it just not works on my iPhone.But when i use the .json file download from the official blog,things work fine.So in one word,the json file rendered by my own After Effect doesn't work.

• After Effect CC 2015 & bodymovin 4.5.4

I would like to ask what Lottie is the tool used to do animation

Support for image layers

Thanks for making this awesome tool!

We'd love to use it, but we'd need support for image-backed layers to use our existing after effects animations. From taking a quick glance through the code, it would appear that our image layers are being ignored as they map to the LALayerTypeUnknown type. Below is the entirety of one of our simple exports with an image. Here's a link to a bodymovin image layer schema as well.

I'd be happy to take a stab at this if this is a feature you'd be interested in adding. Thanks!

{
    "assets": [{
        "id": "image_0",
        "w": 811,
        "h": 976,
        "u": "images/",
        "p": "img_0.png"
    }, {
        "id": "image_1",
        "w": 1039,
        "h": 1283,
        "u": "images/",
        "p": "img_1.png"
    }],
    "layers": [{
        "ddd": 0,
        "ind": 0,
        "ty": 2,
        "nm": "Link.png",
        "cl": "png",
        "refId": "image_0",
        "ks": {
            "o": {
                "k": 100
            },
            "r": {
                "k": [{
                    "i": {
                        "x": [0.667],
                        "y": [1]
                    },
                    "o": {
                        "x": [0.333],
                        "y": [0]
                    },
                    "n": ["0p667_1_0p333_0"],
                    "t": 60,
                    "s": [0],
                    "e": [-5]
                }, {
                    "i": {
                        "x": [0.667],
                        "y": [1]
                    },
                    "o": {
                        "x": [0.333],
                        "y": [0]
                    },
                    "n": ["0p667_1_0p333_0"],
                    "t": 65,
                    "s": [-5],
                    "e": [5]
                }, {
                    "i": {
                        "x": [0.667],
                        "y": [1]
                    },
                    "o": {
                        "x": [0.333],
                        "y": [0]
                    },
                    "n": ["0p667_1_0p333_0"],
                    "t": 70,
                    "s": [5],
                    "e": [-5]
                }, {
                    "i": {
                        "x": [0.667],
                        "y": [1]
                    },
                    "o": {
                        "x": [0.333],
                        "y": [0]
                    },
                    "n": ["0p667_1_0p333_0"],
                    "t": 75,
                    "s": [-5],
                    "e": [5]
                }, {
                    "i": {
                        "x": [0.667],
                        "y": [1]
                    },
                    "o": {
                        "x": [0.333],
                        "y": [0]
                    },
                    "n": ["0p667_1_0p333_0"],
                    "t": 80,
                    "s": [5],
                    "e": [0]
                }, {
                    "t": 85
                }]
            },
            "p": {
                "k": [1308, 572, 0]
            },
            "a": {
                "k": [405.5, 488, 0]
            },
            "s": {
                "k": [75, 75, 100]
            }
        },
        "ao": 0,
        "ip": 0,
        "op": 252,
        "st": 0,
        "bm": 0,
        "sr": 1
    }, {
        "ddd": 0,
        "ind": 1,
        "ty": 2,
        "nm": "keys.png",
        "cl": "png",
        "refId": "image_1",
        "ks": {
            "o": {
                "k": 100
            },
            "r": {
                "k": [{
                    "i": {
                        "x": [0.667],
                        "y": [1]
                    },
                    "o": {
                        "x": [0.333],
                        "y": [0]
                    },
                    "n": ["0p667_1_0p333_0"],
                    "t": 0,
                    "s": [0],
                    "e": [-2]
                }, {
                    "i": {
                        "x": [0.667],
                        "y": [1]
                    },
                    "o": {
                        "x": [0.333],
                        "y": [0]
                    },
                    "n": ["0p667_1_0p333_0"],
                    "t": 5,
                    "s": [-2],
                    "e": [2]
                }, {
                    "i": {
                        "x": [0.667],
                        "y": [1]
                    },
                    "o": {
                        "x": [0.333],
                        "y": [0]
                    },
                    "n": ["0p667_1_0p333_0"],
                    "t": 10,
                    "s": [2],
                    "e": [-2]
                }, {
                    "i": {
                        "x": [0.667],
                        "y": [1]
                    },
                    "o": {
                        "x": [0.333],
                        "y": [0]
                    },
                    "n": ["0p667_1_0p333_0"],
                    "t": 15,
                    "s": [-2],
                    "e": [2]
                }, {
                    "i": {
                        "x": [0.667],
                        "y": [1]
                    },
                    "o": {
                        "x": [0.333],
                        "y": [0]
                    },
                    "n": ["0p667_1_0p333_0"],
                    "t": 20,
                    "s": [2],
                    "e": [0]
                }, {
                    "t": 25
                }]
            },
            "p": {
                "k": [580, 524, 0]
            },
            "a": {
                "k": [287.5, 641.5, 0]
            },
            "s": {
                "k": [75, 75, 100]
            }
        },
        "ao": 0,
        "ip": 0,
        "op": 251,
        "st": 0,
        "bm": 0,
        "sr": 1
    }, {
        "ddd": 0,
        "ind": 2,
        "ty": 1,
        "nm": "Yellow Solid 1",
        "ks": {
            "o": {
                "k": 100
            },
            "r": {
                "k": 0
            },
            "p": {
                "k": [960, 540, 0]
            },
            "a": {
                "k": [960, 540, 0]
            },
            "s": {
                "k": [100, 100, 100]
            }
        },
        "ao": 0,
        "sw": 1920,
        "sh": 1080,
        "sc": "#ffc400",
        "ip": 0,
        "op": 263,
        "st": 0,
        "bm": 0,
        "sr": 1
    }],
    "v": "4.5.3",
    "ddd": 0,
    "ip": 0,
    "op": 240,
    "fr": 60,
    "w": 1920,
    "h": 1080
}

Linear position keyframes are eased

So I'm doing a position transform on a layer and in AE it runs linearly. When I run it on device (iOS) it looks like it runs linearly until the last 80% of the animation and then it slows down.

Any reason why?

Animation Trim Multiple Shapes Individually (implemented in bodymovin) but not in Lottie yet

I've been trying out this aep.
In After effects:

The result is this json file: https://www.dropbox.com/s/8r807g1hcntrzt7/rocket.json?dl=0

The result:

Bodymovin Settings, if it helps:

Carthage installation documentation is wrong

The readme states:

In your application targets “General” tab under the “Embedded Binaries” section, drag and drop lottie-ios.framework from the Carthage/Build/iOS directory that carthage update produced.

However, this is not correct. According to Carthage, you need to

On your application targets’ “General” settings tab, in the “Linked Frameworks and Libraries” section, drag and drop each framework you want to use from the Carthage/Build folder on disk.

Carthage Readme

Methods don't follow swift 3 guidelines

let animationView = LAAnimationView.animationNamed(animationNamed: "foobar")

should really be

let animationView = LAAnimationView.animation(named: "foobar")

https://swift.org/documentation/api-design-guidelines/

Pod installed but framework not found Lottie

ld: warning: directory not found for option '-F/Users/jingqiyanglois/Library/Developer/Xcode/DerivedData/lottie-ios-cpbpeohptyuobhbmovrxchqlbhcp/Build/Products/Debug-iphonesimulator/lottie-ios-iOS'
ld: framework not found Lottie
clang: error: linker command failed with exit code 1 (use -v to see invocation)

I used cocoapod to install but still fail to have the framework working. Any solutions?

Pause animation at a specified progress amount

Just having a look at this project and it looks great! One thing that seems to be missing though is the ability to pause an animation at an amount of progress. So imagine being able to play to say 50% of the way through then automatically pause.

Why might this be handy?
Well imagine a play/pause button that we want to animate when the user taps it. So the sequence of events would be:
[user taps] -> animate from play to pause
[user taps again] -> animate from pause to play (this is not just the reverse of the first animation)

We could use one animation for that, if we had the ability to tell the framework to only play 50% of the animation, then later from 50% to completion (that second part already exists). I've attached the animation in question so that hopefully this makes more sense.

playpause5.json.zip

I might be missing something, but having support for things that have 2 states and going between them seems fairly common?

Reverse Animation

Is there a way to set the current progress and then set the end progress and then animate?

Ex:
ToValue: 0.0
FromValue: 0.5

"duration" returns seconds on iOS, milliseconds on Android

Not much more to say I guess. iOS returns the playback duration in seconds, Android in milliseconds. The general unit for playback durations is in milliseconds, so they should probably be normalized.

Animated Keyboard crash !!

*** Terminating app due to uncaught exception 'NSRangeException', reason: '-[__NSCFString replaceCharactersInRange:withString:]: Range or index out of bounds'

JSON File not working

@buba447
Awesome Library, thanks for sharing it with us!

From After Effect, I generated JSON File with the help of https://github.com/bodymovin/bodymovin#bodymovin, It gave me two files one is data.json file and second is img.png file.

Then due to issue of Cocoapods, I included these two files in Example Provided by this library.
In this project, I changed in LottieRootViewController,

- (void)viewDidLoad {
[super viewDidLoad];
...........
self.lottieLogo = [LAAnimationView animationNamed:@"data copy"]; //was LottieLogo1 self.lottieLogo.contentMode = UIViewContentModeScaleAspectFill;
[self.view addSubview:self.lottieLogo];

But, didn't working.
Provide some proper guidance, how actually this works?

Here is two files:
data copy.txt

change its extension from data copy.txt -> data copy.json

and below is .png file,

Set animationProgress to end

I've been trying to see if I can set the animation to it's end, or 'animationProgress = 1.0', in case I want to see it at it's finished state without having it go through the animation. I know I could just use a still image instead, but is this possible?

bugs with typing!

When I typing something some letters still playing animations.Like this picture

Reset Animation

I'm speaking in particular to iOS. Is there currently a way for an animation to be reset before it completes?

Separate Dimensions - Position Transform

I was using Facebook Keyframes and have recently been testing lottie. I've encountered a few issues with exports I specifically adapted to be used in Keyframes that render correctly in bodymovin and keyframes, but not in lottie. After some trouble shooting I was able to fix the problem by un-separating the dimensions for the position transforms on layers that had previously been separated.

Separating position transform dimensions is often a significant part of my workflow and it would be useful to maintain this functionality.

Deployment target is too high (builds fail)

I cloned the repo and attempted to build the project for iPhone but Xcode reported the project could not be built for my 10.1 iPhone because the deployment target is 10.2. This feels unnecessary.

I did this because building with Carthage was giving me:

Ineligible destinations for the "Lottie" scheme:
		{ platform:iOS, id:dvtdevice-DVTiPhonePlaceholder-iphoneos:placeholder, name:Generic iOS Device }
		{ platform:iOS Simulator, id:dvtdevice-DVTiOSDeviceSimulatorPlaceholder-iphonesimulator:placeholder, name:Generic iOS Simulator Device }

After lowering the deployment target, things worked fine.

3d Layers Crash

If a layer is set as a 3d layer in after effects Lottie crashes since the rotation values are split into 3 separate values.

Latest master issues with Carthage framework

Ran carthage update and tried adding the iOS framework as embedded, compiled and got this

Null is assigned to a _Nonnull pointer

/lottie-ios/lottie-ios/Classes/Private/LOTAnimationView.m:272:15: Null is assigned to a pointer which is expected to have non-null value

Static analiser is our friend.

should consider exposing containing CALayer for animations

Even though it appears all of the animating happens in the domain of Core Animation, the animations can only be accessed via UIView. Would be nice to be able to instantiate animations for CALayers as well, so that they may be used in contexts which require layers.

GitHub API request failed: DoesNotExist

I followed the guide to get the Lottie Framework with Carthage, But I get the message indicating "GitHub API request failed: DoesNotExist" on the terminal,I have been searching the solution from network and I am failed. Please tell me how I can solve this problem! Thank you very much！

Crash when i continuous typing on TypingDemoViewController

*_Platform: iOS 10.3
*_Console: *** Terminating app due to uncaught exception 'NSRangeException', reason: '-[__NSCFString replaceCharactersInRange:withString:]: Range or index out of bounds'
*** First throw call stack:
(0x183663fac 0x1820c853c 0x183663ef4 0x183601e8c 0x10007e1e8 0x10007cbf8 0x189a7a63c 0x189a4353c 0x189cb0808 0x189cb0430 0x18a31231c 0x189cb036c 0x189a431c4 0x189a42aec 0x189a410dc 0x189a3f374 0x189cc6fc4 0x1898b38a8 0x189cc6c74 0x1898bdc7c 0x1898b91c8 0x189889e9c 0x18a07f920 0x18a07a09c 0x18a07a4a8 0x1836123c8 0x183611d38 0x18360f944 0x18353f9bc 0x184fac074 0x1898ee984 0x100081028 0x18254d59c)
libc++abi.dylib: terminating with uncaught exception of type NSException

Missing description under title

Add topics to improve library discovery

Hi, thanks for the awesome project 👍
Recently the GitHub released topics I think it makes sense to add them to let more people find the framework.

Memory management issues when AE uses too much mask for animation

When AE animation uses a lot of mask, there's some bug on memory management.

Swift

Can't seem to be able to get LAAnimationView to work. I have installed using carthage, added briging header. It finds LottieVersionNumber but not LAAnimationView? Anything I have missed?

Unable to find a specification for `lottie-ios`

how to solve? thanks

Add Support for Looping at Certain Progress

I have some animations which are designed to play a small "intro", then play the "main" part of the animation. The "main" part of the animation is to then be looped (to save space) either indefinitely or for a particular number of loops (specified outside of After Effects, obviously).

In my current system I have the ability to specify a frame/progress percentage in which the animation will start from when looping as well as a loop count. It would be a nice if a similar feature existed in Lottie.

I've tried using a completion callback and setting loopAnimation to be false to get similar behavior, but I seem to be hitting a race condition or logical error in which the animation's completion callback will be called once, but not called a second time. Setting animationProgress in the completion callback also does not appear to do anything.

Add image support

my animator need to operate some .png img ,build a new folder "images" and put .png file in it .
json like this:"
{
"assets": [
{
"id": "image_0",
"w": 960,
"h": 540,
"u": "images/",
"p": "img_0.png"
}
],
...
} "
but I has run app ,can't see anything without empty

add support for video Export usage

I want to export this amazing animation into my video file with AVFoundation.

let animationView = LAAnimationView.animationNamed("hamburger")

let parentLayer: CALayer = CALayer()
let videoLayer: CALayer = CALayer()
videoLayer.frame = CGRect(x: 0, y: 0, width: renderSize.width, height: renderSize.height)
parentLayer.frame = CGRect(x: 0, y: 0, width: renderSize.width, height: renderSize.height)
parentLayer.addSublayer(videoLayer)

parentLayer.addSublayer(animationView.layer)

composition.animationTool = AVVideoCompositionCoreAnimationTool(postProcessingAsVideoLayer: videoLayer, in: parentLayer)

but the animation does not shown in the composed video. I thought the animation begin time is not correct. It should be AVCoreAnimationBeginTimeAtZero

can you add this feature in this amazing animation library ?

AVSynchronizedLayer Issue

It is not working with AVSynchronizedLayer. I am adding LOTAnimationView layer to AVSynchronizedLayer and setting begin time to CACurrentMediaTime(). But nothing happens. If I will add LOTAnimationView layer to any other CALayer then it works fine. Any suggestions for that?

Category Methods should be prefixed

The methods added in UIColor+Expanded and CAAnimationGroup+LAAnimatableGroup should be prefixed to avoid name collisions.

Avoid Category Method Name Clashes
https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/CustomizingExistingClasses/CustomizingExistingClasses.html#//apple_ref/doc/uid/TP40011210-CH6-SW4

This is related to #16

Can't compile using Carthage Framework

See attached
Xcode.zip

Can I use this library with Swift?

Hello guys,

Awesome Library, thanks for sharing it with us! One quick question: Is it possible to use this library with swift? And if I can, how so?

Animated composition

Hello guys! Nicely done.

I have a question. Does lottie support transforms on composition? Something like on the screenshot:

If not, are you planning to add it in the nearest future? I could try to do it myself, in case you don't have such plans. I saw some class named LACustomChild, is it related?

Thanks!

iOS/Android device form factor - design pattern (for Edge to Edge animation)

I've noticed that each device (iPhone 5, 6 and 6+) form factors, require each it's own aep (and it's own .json) composition reflecting the size of the targeted device for pixel perfect edge to edge screen animation (example, placing a border around the screen).

In other words, for each of the iPhone device form factor, the Compositions are:

• iPhone 5: 568 x 320
• iPhone 6, 7: 667 x 375
• iPhone 6, 7 Plus: 736 x 414

My question is, is there a design pattern (or composition) to follow in order to generate one json file for all form factors (including Androids) ?

For non edge to edge compositions, the animations should be centered at the smallest form factor size.

Outdated version on Cocoapods

The current version pushed to the Cocoapods trunk is 1.0.0 which is not inline with the latest version 1.0.3.

Is transparency supported?

Tried to create a simple animation showing that something is being calculated:

http://gph.is/2kyQMdP

This seems to work perfectly fine through bodymovin, but when I transfer it to Lottie and play it through XCode I lose the transparency where the buttons are.

http://gph.is/2jTu1Ve

So I am wondering how I should maintain the transparency seen in the first gif when using Lottie?

a11y

Do text Animations expose an accessibility id? Is there a mechanism for enabling or enhancing Accessibility for these custom views/layers?

Doesn't work with text animations?

Tried with the attached json file (in zip) that has a super simple text animation, but no no luck... What might be reason?

text.zip