Getting Started

Supported Devices

Currently this package supports a minimum iOS version of 13.0+ for iPhone and iPad. MacOS is supported for versions 11.0 and upwards.

Usage

  1. Install the dependancy

Via the Swift Package Manager

To install via Swift Package Manager, in the package finder in Xcode, search for LottieFiles/dotlottie-ios or use the full Github path: https://github.com/LottieFiles/dotlottie-ios

  1. Import DotLottie
import DotLottie
  1. How to use

The DotLottieAnimation class will store the playback settings of your animation. It will also allow you to control playback via the play / pause functions.

3a. SwiftUI

Set up DotLottieAnimation inside a View. Optionally pass playback settings.

Load from an animation (.lottie / .json) from the main asset bundle.

struct AnimationView: View {
    var body: some View {
        DotLottieAnimation(
            fileName: "cool_animation",
            config: AnimationConfig(autoplay: true, loop: true)
        ).view()
    }
}

Load an animation (.lottie / .json) from the web.

struct AnimationView: View {
    var body: some View {
        DotLottieAnimation(
            webURL: "https://lottie.host/link.lottie",
            config: AnimationConfig(autoplay: true)
        ).view()
    }
}

Load directly from a String (.json).

struct AnimationView: View {
    var body: some View {
        DotLottieAnimation(
            animationData: "{\"v\":\"4.8.0\",\"meta\":{\"g\":\"LottieFiles AE...",
            config: AnimationConfig(autoplay: true)
        ).view()
    }
}

Load from .lottie Data.

struct AnimationView: View {
    let dotLottieData: Data // Your .lottie file data


    var body: some View {
        DotLottieAnimation(
            dotLottieData: dotLottieData,
            config: AnimationConfig(autoplay: true)
        ).view()
    }
}

Load from .json or .lottie Data.

struct AnimationView: View {
    let animationData: Data // Your animation file data


    var body: some View {
        DotLottieAnimation(
            lottieData: animationData,
            config: AnimationConfig(autoplay: true)
        ).view()
    }
}

3b. UIKit - Storyboard

Coming soon!

3c. UIKit - Programmatic approach

class AnimationViewController: UIViewController {
    var simpleVM = DotLottieAnimation(
        webURL: "https://lottie.host/link.lottie",
        config: AnimationConfig(autoplay: true, loop: false)
    )


    override func viewWillAppear(_ animated: Bool) {
        let dotLottieView = simpleVM.view()
        view.addSubview(dotLottieView)
    }
}

Multi-threading Support

You can enable multi-threading support by passing a threads parameter to improve performance:

let animation = DotLottieAnimation(
    fileName: "animation",
    config: AnimationConfig(autoplay: true),
    threads: 4  // Number of threads to use
)

AnimationConfig

The AnimationConfig struct allows you to configure various aspects of your animation:

let config = AnimationConfig(
    autoplay: true,
    loop: true,
    mode: .forward,
    speed: 1.5,
    useFrameInterpolation: true,
    segments: (10, 50),  // Play frames 10-50
    backgroundColor: .clear,
    width: 300,
    height: 300,
    marker: "intro",
    themeId: "dark",
    stateMachineId: "main",
    animationId: "loading"
)

Configuration Properties

PropertyTypeDescription
autoplayBool?Whether animation should start playing automatically
loopBool?Whether animation should loop continuously
modeMode?Playback mode (.forward, .reverse, .bounce, etc.)
speedFloat?Playback speed multiplier
useFrameInterpolationBool?Whether to use frame interpolation for smoother animation
segments(Float, Float)?Start and end frames for partial playback
backgroundColorCIImage?Background color for the animation canvas
widthInt?Override animation width
heightInt?Override animation height
layoutLayout?Layout configuration for the animation
markerString?Marker name for timeline navigation
themeIdString?Theme ID to apply (for .lottie files)
stateMachineIdString?State machine ID to load
animationIdString?Specific animation ID to play (for multi-animation .lottie files)

Enums and Types

Mode

Playback mode options:

  • .forward - Play animation forward
  • .reverse - Play animation in reverse
  • .bounce - Play forward then reverse
  • .bounceReverse - Play reverse then forward

Fit

Layout fit options for animation sizing:

  • .contain - Scale to fit within bounds while maintaining aspect ratio
  • .fill - Scale to fill bounds (may crop)
  • .fitWidth - Scale to fit width
  • .fitHeight - Scale to fit height
  • .none - No scaling

Layout

Configuration for animation positioning and scaling:

let layout = Layout(fit: .contain, align: [0.5, 0.5]) // Center alignment

OpenUrlPolicy

Security policy for state machine URL opening:

let urlPolicy = OpenUrlPolicy(
    requireUserInteraction: true,  // Require user interaction before opening URLs
    whitelist: ["https://trusted-domain.com"]  // Allowed domains
)

View Creation

The DotLottieAnimation class provides different view creation methods for different platforms and UI frameworks:

// SwiftUI view (cross-platform)
let animation = DotLottieAnimation(fileName: "animation", config: config)
let swiftUIView = animation.view() // Returns DotLottieView


// UIKit view (iOS only)
#if os(iOS)
let uikitView = animation.view() // Returns DotLottieAnimationView
#endif

Additional Features

Manifest Information

For .lottie files, you can access manifest information:

if let manifest = animation.manifest() {
    print("Animations: \(manifest.animations)")
    print("Themes: \(manifest.themes ?? [])")
    print("State Machines: \(manifest.stateMachines ?? [])")
}


// Get available markers
let markers = animation.markers()
for marker in markers {
    print("Marker: \(marker.name) at time \(marker.time)")
}

Usage

How to use the various features of the dotLottie player.

API

The various ways of controlling your animations.

Methods

The various ways of controlling your animations.

Interactivity

Interactivity methods available for dotLottie-ios