Lottie 4.3.0 now available, with official support for SwiftUI

[calda]

Today we released Lottie 4.3.0. This version adds many new features, including:

• Official support for SwiftUI!
• A public Core Animation CALayer subclass
• Support for reduced motion
• Support for drop shadow layer effects
• Support for visionOS

SwiftUI support

Lottie 4.3.0 introduces a new LottieView SwiftUI component, which wraps the UIKit LottieAnimationView but provides new, reimagined declarative APIs. Let’s take a quick tour of some of the functionality available in the new LottieView:

Loading Lottie animations

LottieView includes a robust set of APIs for loading and displaying Lottie animations from .json files and .lottie files, both synchronously and asynchronously.

You can easily load Lottie animations from json files or dotLottie files available locally:

// Displaying a Lottie animation from the local StarAnimation.json file
LottieView(animation: .named("StarAnimation")) 

// Displaying a Lottie animation from the local StarAnimation.lottie file
LottieView {
  try await DotLottieFile.named("StarAnimation")
}

// Displaying either a LottieAnimation or DotLottieFile
LottieView {
  if isDotLottieFile {
    try await DotLottieFile.named(animationName).animationSource
  } else {
    LottieAnimation.named(animationName)?.animationSource
}

You can also easily load animations by downloading them from a URL, optionally displaying a placeholder view until the animation finishes downloading:

LottieView {
  try await LottieAnimation.loadedFrom(url: myRemoteAnimationURL)
} placeholder: {
  LoadingIndicator()
    .frame(width: 50, height: 50)
}

Declarative playback

LottieView provides some convenience APIs for the most common types of animation playback. The specified animation starts playing as soon as the animation finishes loading:

// Play the animation once, from the start to the end
LottieView(animation: .named("StarAnimation")) 
  .playing()
  
// Loop the animation from the start to the end
LottieView(animation: .named("StarAnimation")) 
  .looping()
  
// Display the animation paused at the half way mark
LottieView(animation: .named("StarAnimation")) 
  .currentProgress(0.5)

LottieView also provides a playbackMode API that takes a declarative LottiePlaybackMode value, which you can use to update the playback mode in response to state updates.

Here’s an example that triggers a Lottie animation to play when you press a button:

// The Lottie animation is controlled by this SwiftUI state
@State var playbackMode = LottiePlaybackMode.paused

var body: some View {
  HStack {
    LottieView(animation: .named("HeartAnimation"))
      .playbackMode(playbackMode)
      .animationDidFinish { _ in
        playbackMode = .paused
      }
  
    // When the button is pressed, trigger the animation to start playing from the beginning
    Button {
      playbackMode = .playing(.fromProgress(0, toProgress: 1, loopMode: .playOnce))
    } label: {
      Image(systemName: "play.fill")
    }
  }
}

All of the most common LottieAnimationView APIs are available on LottieView adapted to fit the declarative model of SwiftUI. If you need to call an API on LottieAnimationView which is not yet available on LottieView, you can access the underlying LottieAnimationView via the configure { ... } method:

LottieView(animation: .named("StarAnimation"))
  // The configure closure is called on every SwiftUI state update
  .configure { lottieAnimationView in
    // LottieAnimationView has some APIs which are not yet available
    // on LottieView directly, but you can still access them here:
    lottieAnimationView.shouldRasterizeWhenIdle = true
    lottieAnimationView.logHierarchyKeypaths()
  }

Buttons and switches

Lottie 4.3.0 also includes SwiftUI implementations of the UIKit AnimatedSwitch and AnimationButton APIs, also adapted for SwiftUI. This version also adds macOS support to the entire family of animated controls, including the new SwiftUI versions.

Here’s an example LottieSwitch that tracks whether or not it’s enabled in an isOn property:

@State var isOn = false

var body: some View {    
  HStack {
    LottieSwitch(animation: .named(animationName))
      .isOn($isOn)
      .onAnimation(fromProgress: 0.5, toProgress: 1.0)
      .offAnimation(fromProgress: 0.0, toProgress: 0.5)

    Text(verbatim: "\(title) (isOn=\(isOn))")
  }
}

and here’s an example LottieButton that tracks the number of times its been pressed in a pressCount property:

@State var pressCount = 0

var body: some View {
  HStack {
    LottieButton(animation: .named(animationName)) {
      pressCount += 1
    }
    .animate(fromMarker: "touchDownStart", toMarker: "touchDownEnd", on: .touchDown)
    .animate(fromMarker: "touchDownEnd", toMarker: "touchUpCancel", on: .touchUpOutside)
    .animate(fromMarker: "touchDownEnd", toMarker: "touchUpEnd", on: .touchUpInside)

    Text(verbatim: "\(title) (pressCount=\(pressCount))")
  }
}

Core Animation CALayer API

Lottie is built on top of Core Animation CALayers, which is how we’ve been able to make it available on both iOS and macOS. Historically this was just an implementation detail, since only LottieAnimationView itself (a UIView / NSView implementation) was public.

Lottie 4.3.0 adds a new LottieAnimationLayer, a public CALayer subclass. All of the functionality in LottieAnimationView has been moved to LottieAnimationLayer, and now the UIView implementation simply wraps the underlying LottieAnimationLayer.

This functionality was added in collaboration with engineers from Meta (thanks!). This enabled them to add support for Lottie to the popular design tool Origami, which is built using Core Animation CALayers rather than UIKit or AppKit:

Support for reduced motion

Reduced motion is an important accessibility option on iOS. We’ve been adding support for this system flag in more places throughout the Airbnb app. We’re especially interested in ways to make this automatic, so feature developers get the correct behavior without having to implement it themselves.

There isn't a sufficiently general way for Lottie to decide how to handle reduced motion for an arbitrary animation, since the correct behavior depends on the use case. For example, we can't just always display the first frame of the animation, because that may just be entirely blank.

Instead, Lottie 4.3.0 adds support for “reduced motion” markers. If your animation has a marker named “reduced motion” (or some variation like “reducedMotion” etc), Lottie will override the play methods to always play that specific marker any time UIAccessibility.isReduceMotionEnabled is true.

Here’s an example of an animation that includes a “reduced motion” marker with a start frame pointing to the last frame in the animation, and a marker duration of zero:

Reduced motion disabled	Reduced motion enabled

If the user has reduced motion enabled (meaning UIAccessibility.isReduceMotionEnabled returns true), Lottie automatically displays the last frame of the animation rather than animating it from the start to the end. No extra code required!

We’re hoping to bring similar behavior to web and Android in the future, so it can become part of the cross-platform Lottie standard.

Support for drop shadow layer effects

Lottie now includes support for rendering and animating drop shadow layer effects. This means drop shadows are finally supported on all platforms (iOS, Android, and web), meaning designers can safely and confidently use them in Lottie animations shared across all platforms!

Support for visionOS

Lottie 4.3.0 adds support for using Lottie on visionOS! Here’s a gif of the repo’s SwiftUI example app running in the Apple Vision Pro simulator:

The lottie-spm repo uses prebuilt XCFramework archives, which we must compile using a production version of Xcode. Since the Apple Vision Pro hasn’t been released yet, only beta versions of Xcode include the visionOS SDK. That means that we can’t support visionOS via the lottie-spm package quite yet. If you need visionOS support in your project, you’ll need to use the lottie-ios repo directly for now.

Full changelog

There’s tons of other new functionality and fixes included in Lottie 3.4.0. A full changelog is available here: https://github.com/airbnb/lottie-ios/releases/tag/4.3.0

Thanks to everyone who contributed to this release!

[matinzd]

Great job! Thanks for this release 👍
I also bumped lottie-ios in react native repository as well.

[freak4pc]

Great news! I had two questions which are specifically SwiftUI API-surface related

One thing I'm wondering about is why not using a Binding for the playback mode of the play() method?
That would remove the need to update the end state by hand after the playing is done.

Also wondering if the naming of play() is right here, since it smells like imperative "play this now" instead of state-driven, i.e. .playing($isPlaying) or a playbackMode(...) modifier to begin with, similar to SwiftUI API such as hidden(), focused() etc.

Maybe you've already considered and discussed just but just popped to my head :)
Regardless awesome having a native SwiftUI view bundled into Lottie itself, finally! :)

[calda]

One thing I'm wondering about is why not using a Binding for the playback mode of the play() method?
That would remove the need to update the end state by hand after the playing is done.

This could be a nice way to simplify the playOnce use case. It seems like a good idea to also have an API that doesn't require a binding, since with looping animations the animation plays indefinitely so the binding would never actually be updated from within LottieView. We could certainly add an additional overload that takes a binding.

Also wondering if the naming of play() is right here, since it smells like imperative "play this now" instead of state-driven, i.e. .playing($isPlaying) or a playbackMode(...) modifier to begin with, similar to SwiftUI API such as hidden(), focused() etc.

We provide both a play and playbackMode method.

[freak4pc]

That's a good point about the looping. Thanks!

[calda]

We just released 4.3.2 which improves the naming here, from "play" to "playing" etc

Before

// Loop from 0.5 to 1.0
LottieView(animation: myAnimation)
  .play(.fromProgress(0.5, toProgress: 1.0, loopMode: .loop))

// Pause at the halfway point of the animation
LottieView(animation: myAnimation)
  .play(.progress(0.5))

After

// Loop from 0.5 to 1.0
LottieView(animation: myAnimation)
  .playing(.fromProgress(0.5, toProgress: 1.0, loopMode: .loop))

// Pause at the halfway point of the animation
LottieView(animation: myAnimation)
  .paused(at: .progress(0.5))

[asiergmorato]

Hi! Does it work with watchOS now?

[motionz-von]

Nope! just tested

[codemagmanlele]

How do you reduce the animation speed with swiftUI ?

[calda]

There's a .animationSpeed(...) modifier