Command Palette

Search for a command to run...

dotLottie iOS Player API Reference

API reference for the dotLottie iOS player. Covers DotLottiePlayerView (SwiftUI), DotLottiePlayerUIView (UIKit/AppKit), DotLottieAnimation, config, enums, protocols, and state machine controls.

dotLottie iOS Player API Reference

The iOS player provides three ways to display animations:

  • DotLottiePlayerView — A SwiftUI view with a builder-pattern modifier API.

  • DotLottiePlayerUIView — A UIKit/AppKit view with property-based API.

  • DotLottieAnimation — A lower-level view model that can be used with .view().

DotLottiePlayerView (SwiftUI)

A SwiftUI view for displaying Lottie and dotLottie animations. Uses a declarative modifier API.

Initializers

InitializerDescription
init(animation:)Create a player with a DotLottieAnimation instance.
init(_ loadAnimation:)Create a player with an async closure that returns a DotLottieAnimation.
init(_ loadAnimation:placeholder:)Create a player with an async closure and a custom placeholder view shown during loading.

Modifiers

All modifiers return Self and can be chained.

ModifierDescription
.configure(_:)Apply a configuration closure to the underlying animation.
.looping()Enable looping playback.
.playing()Set the playback state to playing.
.paused()Set the playback state to paused.
.loopMode(_:)Set the loop mode (DotLottieLoopMode).
.playbackMode(_:)Set the playback mode (DotLottiePlaybackMode).
.animationSpeed(_:)Set the playback speed multiplier.
.configuration(_:)Apply an AnimationConfig to the player.
.animationDidLoad(_:)Register a callback invoked when the animation finishes loading.
.currentProgress(_:)Set the current playback progress (0.0–1.0).
.currentFrame(_:)Set the current frame number.
.mode(_:)Set the playback Mode (forward, reverse, bounce, bounceReverse).
.useFrameInterpolation(_:)Enable or disable frame interpolation.
.segments(_:)Set the playback segment as a (Float, Float) range.
.reloadAnimationTrigger(_:showPlaceholder:)Trigger a reload of the animation. Optionally shows the placeholder during reload.

Example

import SwiftUI
import DotLottie

struct ContentView: View {
    var body: some View {
        DotLottiePlayerView(animation: DotLottieAnimation(
            fileName: "animation",
            config: AnimationConfig(autoplay: true, loop: true)
        ))
        .looping()
        .playing()
        .animationSpeed(1.5)
        .frame(width: 300, height: 300)
    }
}

Async loading with placeholder

DotLottiePlayerView({
    try await DotLottieAnimation(
        webURL: "https://example.com/animation.lottie",
        config: AnimationConfig(autoplay: true, loop: true)
    )
}, placeholder: {
    ProgressView()
})
.looping()
.playing()

DotLottiePlayerUIView (UIKit / AppKit)

A UIView (iOS) / NSView (macOS) for displaying Lottie and dotLottie animations with a property-based API.

Initializers

InitializerDescription
init(dotLottieAnimation:config:)Create a player with an existing DotLottieAnimation and optional config.
init(name:bundle:config:completion:)Load an animation by file name from a bundle.
init(filePath:config:completion:)Load an animation from a file path.
init(url:config:session:completion:)Load an animation from a URL.
init(animationData:config:)Load an animation from a JSON string.
init(dotLottieData:config:)Load an animation from raw .lottie Data.

Properties

PropertyTypeDescription
dotLottieAnimationDotLottieAnimationThe underlying animation instance.
configAnimationConfigThe current animation configuration.
isAnimationPlayingBoolWhether the animation is currently playing.
isAnimationPausedBoolWhether the animation is currently paused.
isAnimationStoppedBoolWhether the animation is currently stopped.
loopModeDotLottieLoopModeThe current loop mode (.playOnce or .loop).
animationSpeedFloatThe current playback speed multiplier.
currentProgressFloatThe current playback progress (0.0–1.0).
currentFrameFloatThe current frame number.
totalFramesFloatThe total number of frames.
durationFloatThe total animation duration in milliseconds.
modeModeThe current playback mode.
useFrameInterpolationBoolWhether frame interpolation is enabled.
segments(Float, Float)The current playback segment range.
animationLoaded(() -> Void)?Callback invoked when the animation finishes loading.

Playback Methods

MethodReturn TypeDescription
play()VoidBegin playback.
pause()VoidPause playback.
stop()VoidStop playback and reset to the initial frame.
play(fromProgress:toProgress:loopMode:)VoidPlay between two progress values with an optional loop mode.
play(fromFrame:toFrame:loopMode:)VoidPlay between two frame numbers with an optional loop mode.
play(marker:loopMode:)VoidPlay a named marker segment with an optional loop mode.
play(fromMarker:toMarker:loopMode:)VoidPlay between two named markers with an optional loop mode.
setFrame(_:)VoidSeek to a specific frame.
setProgress(_:)VoidSeek to a specific progress value (0.0–1.0).

Marker Methods

MethodReturn TypeDescription
markers()[Marker]Returns all markers in the animation.
setMarker(_:)VoidSet the active marker for playback.
progressTime(forMarker:)Float?Get the progress time for a named marker.
frameTime(forMarker:)Float?Get the frame time for a named marker.
durationFrameTime(forMarker:)Float?Get the duration in frames for a named marker.

Animation & Manifest Methods

MethodReturn TypeDescription
loadAnimation(byId:)VoidLoad a specific animation by ID from a multi-animation .lottie file.
manifest()Manifest?Returns the .lottie file manifest.

State Machine Methods

MethodReturn TypeDescription
isStateMachine()BoolReturns whether a state machine is active.
startStateMachine(id:openUrlPolicy:)VoidLoad and start a state machine by ID.
stateMachineLoad(id:)BoolLoad a state machine by ID.
stateMachineLoadData(_:)BoolLoad a state machine from a JSON string.
stateMachineStart()BoolStart the loaded state machine.
stateMachineStop()BoolStop the active state machine.
stateMachinePostEvent(_:force:)VoidPost a typed Event to the state machine.
stateMachinePostClickEvent(at:)VoidPost a click event at a position.
stateMachinePostPointerDownEvent(at:)VoidPost a pointer down event at a position.
stateMachinePostPointerUpEvent(at:)VoidPost a pointer up event at a position.
stateMachinePostPointerMoveEvent(at:)VoidPost a pointer move event at a position.
stateMachinePostPointerEnterEvent(at:)VoidPost a pointer enter event at a position.
stateMachinePostPointerExitEvent(at:)VoidPost a pointer exit event at a position.
stateMachineCurrentState()StringReturns the name of the current state.
stateMachineFrameworkSetup()[String]Returns framework setup requirements.
stateMachineGetInputs()[String: String]Returns all state machine inputs and their values.
stateMachineSetNumericInput(key:value:)VoidSet a numeric input value.
stateMachineSetBooleanInput(key:value:)VoidSet a boolean input value.
stateMachineSetStringInput(key:value:)VoidSet a string input value.
stateMachineGetNumericInput(key:)Float?Get a numeric input value.
stateMachineGetBooleanInput(key:)Bool?Get a boolean input value.
stateMachineGetStringInput(key:)String?Get a string input value.
stateMachineSubscribe(_:)VoidSubscribe a StateMachineObserver.
stateMachineUnsubscribe(_:)VoidUnsubscribe a StateMachineObserver.

Example

import UIKit
import DotLottie

class ViewController: UIViewController {
    var playerView: DotLottiePlayerUIView!

    override func viewDidLoad() {
        super.viewDidLoad()

        playerView = DotLottiePlayerUIView(
            name: "animation",
            config: AnimationConfig(autoplay: true, loop: true)
        )
        playerView.frame = CGRect(x: 50, y: 100, width: 300, height: 300)
        view.addSubview(playerView)

        playerView.animationLoaded = {
            print("Animation loaded!")
        }
    }
}

DotLottieAnimation

A lower-level view model for animation playback. Can be used with .view().

Initializers

InitializerDescription
init(fileName:config:)Load an animation by file name from the main asset bundle.
init(webURL:config:)Load an animation from a web URL.
init(animationData:config:)Load an animation from a Lottie JSON string.
init(dotLottieData:config:)Load from raw .lottie Data.
init(lottieData:config:)Load from raw Lottie JSON Data.

AnimationConfig

AnimationConfig defines the playback settings passed to any initializer.

PropertyTypeDefaultDescription
autoplayBoolfalseAutoplay the animation on load.
loopBoolfalseLoop the animation.
speedFloat1.0Playback speed multiplier.
modeMode.forwardPlayback mode: forward, reverse, bounce, bounceReverse.
widthInt512Override animation width.
heightInt512Override animation height.
segment(Float, Float)Play between an interval of frames.
backgroundColorCIImageBackground color of the animation canvas.
useFrameInterpolationBooltrueInterpolate between frames. Useful for smooth playback at slow speeds.
markerStringNamed marker to play on load.
layoutLayoutAnimation layout configuration. See Layout Configuration.
themeIdStringTheme ID to apply on load.
loopCountInt?0Number of times to loop. 0 means infinite when loop is true.
animationIdString?""Animation ID for multi-animation .lottie files.
stateMachineIdString?""State machine ID to auto-load on initialization.

Properties

PropertyTypeDescription
currentFrame()FloatThe currently displayed frame number.
duration()FloatTotal playback time in milliseconds.
totalFrames()FloatTotal number of frames.
loop()BoolWhether looping is enabled.
speed()FloatCurrent playback speed multiplier.
loopCount()IntNumber of completed loops.
mode()ModeCurrent playback mode.
isPaused()BoolWhether the animation is paused.
isStopped()BoolWhether the animation is stopped.
isPlaying()BoolWhether the animation is playing.
isLoaded()BoolWhether the animation has loaded successfully.
error()BoolWhether the animation has errored.
errorMessage()StringError message string, if any.
manifest()ManifestThe .lottie manifest.
segment()(Float, Float)Current playback segment.
backgroundColor()CIImageCurrent background color.
autoplay()BoolWhether autoplay is enabled.
useFrameInterpolation()BoolWhether frame interpolation is enabled.
currentProgress()FloatCurrent playback progress (0.0–1.0).
markers()[Marker]Markers in the animation. See Marker.

Playback Methods

MethodReturn TypeDescription
play()BoolBegin playback from the current position.
pause()BoolPause without resetting position.
stop()BoolStop and return to the initial frame.
play(fromFrame:)BoolStart playback from a specific frame.
play(fromProgress:)BoolStart playback from a specific progress value (0.0–1.0).
setFrame(frame:)BoolSeek to a specific frame.
setProgress(progress:)BoolSeek to a specific progress value (0.0–1.0).
setSpeed(speed:)VoidSet the playback speed multiplier.
setLoop(loop:)VoidEnable or disable looping.
setMode(mode:)VoidSet the playback mode.
setMarker(marker:)VoidSet the active marker for playback.
setSegments(segments:)VoidSet the start and end frame range.
setAutoplay(autoplay:)VoidEnable or disable autoplay.
setFrameInterpolation(_:)VoidEnable or disable frame interpolation.
setBackgroundColor(bgColor:)VoidSet the background color.
resize(width:height:)VoidManually resize the animation canvas.
render()BoolForce a render of the current frame.
tick()VoidRequest and render a single frame.
frameImage()CGImage?Capture the current frame as a CGImage.
getLayerBounds(layerName:)CGRect?Get the bounding box of a named layer.

Animation Management

MethodReturn TypeDescription
loadAnimation(animationId:)VoidLoad a specific animation by ID from the manifest.

Theming & Slots

MethodReturn TypeDescription
setTheme(_:)BoolApply a theme by ID.
setThemeData(_:)BoolApply theme data from a JSON string.
resetTheme()BoolRemove the applied theme.
activeThemeId()StringGet the active theme ID.
setSlots(_:)BoolApply slot data from a JSON string.
clearSlots()BoolClear all slots.
clearSlot(slotId:)BoolClear a specific slot.
setColorSlot(slotId:r:g:b:)BoolSet a color slot with RGB values (0.0–1.0).
setScalarSlot(slotId:value:)BoolSet a scalar slot value.
setTextSlot(slotId:text:)BoolSet a text slot value.
setVectorSlot(slotId:x:y:)BoolSet a vector slot value.
setPositionSlot(slotId:x:y:)BoolSet a position slot value.
setImageSlotPath(slotId:path:)BoolSet an image slot from a file path.
setImageSlotDataUrl(slotId:dataUrl:)BoolSet an image slot from a data URL.

Observer Methods

MethodReturn TypeDescription
subscribe(observer:)VoidSubscribe an Observer to animation events.
unsubscribe(observer:)VoidUnsubscribe an Observer.

State Machine Methods

MethodReturn TypeDescription
stateMachineLoad(id:)BoolLoad a state machine by ID from the manifest.
stateMachineLoadData(_:)BoolLoad a state machine from a JSON string.
stateMachineStart(openUrlPolicy:)BoolStart the loaded state machine.
stateMachineStart(id:openUrlPolicy:)BoolLoad and start a state machine in one call.
stateMachineStop()BoolStop the active state machine.
stateMachineCurrentState()StringGet the name of the current state.
getStateMachine(id:)StringGet a state machine definition JSON by ID.
stateMachinePostEvent(_:force:)VoidPost a typed Event to the state machine.
stateMachineFire(event:)BoolFire a named event string.
stateMachineSubscribe(observer:)VoidSubscribe a StateMachineObserver.
stateMachineUnsubscribe(observer:)VoidUnsubscribe a StateMachineObserver.
stateMachineFrameworkSetup()[String]Get framework setup requirements.
stateMachineGetInputs()[String: String]Get all inputs and their current values.
stateMachineSetBooleanInput(key:value:)VoidSet a boolean input.
stateMachineSetNumericInput(key:value:)VoidSet a numeric input.
stateMachineSetStringInput(key:value:)VoidSet a string input.
stateMachineGetBooleanInput(key:)Bool?Get a boolean input value.
stateMachineGetNumericInput(key:)Float?Get a numeric input value.
stateMachineGetStringInput(key:)String?Get a string input value.

Enums

Mode

public enum Mode {
    case forward
    case reverse
    case bounce
    case bounceReverse
}

DotLottieLoopMode

Used by DotLottiePlayerUIView and DotLottiePlayerView.

public enum DotLottieLoopMode {
    /// Animation plays once then stops.
    case playOnce
    /// Animation loops from beginning to end until stopped.
    case loop
}

DotLottiePlaybackMode

Used by DotLottiePlayerView.

public enum DotLottiePlaybackMode {
    case playing
    case paused
}

Event

Used with stateMachinePostEvent to send typed events to a state machine.

public enum Event {
    case pointerDown(x: Float, y: Float)
    case pointerUp(x: Float, y: Float)
    case pointerMove(x: Float, y: Float)
    case pointerEnter(x: Float, y: Float)
    case pointerExit(x: Float, y: Float)
    case click(x: Float, y: Float)
    case onComplete
    case onLoopComplete
}

Protocols

Observer

Implement this protocol to receive animation playback events via subscribe(observer:).

public protocol Observer {
    func onComplete()
    func onFrame(frameNo: Float)
    func onLoad()
    func onLoadError()
    func onLoop(loopCount: UInt32)
    func onPause()
    func onPlay()
    func onRender(frameNo: Float)
    func onStop()
}

StateMachineObserver

Implement this protocol to receive state machine transition events via stateMachineSubscribe(observer:).

public protocol StateMachineObserver: AnyObject {
    func onTransition(previousState: String, newState: String)
    func onStateEntered(enteringState: String)
    func onStateExit(leavingState: String)
}

Structs

Marker

Returned by the markers() property.

public struct Marker {
    public var name: String
    public var time: Float
    public var duration: Float
}

OpenUrlPolicy

Controls URL opening behavior in state machines.

public struct OpenUrlPolicy: Equatable, Hashable {
    public var requireUserInteraction: Bool  // default: true
    public var whitelist: [String]           // default: []

    public init(requireUserInteraction: Bool = true, whitelist: [String] = [])
}

Manifest

Returned by the manifest() property. Contains metadata about the .lottie file.

Manifest

PropertyTypeDescription
generatorString?Tool that generated the .lottie file.
versionString?dotLottie format version.
animations[ManifestAnimation]All animations bundled in the file.
themes[ManifestTheme]?All themes bundled in the file.
stateMachines[ManifestStateMachine]?All state machines bundled in the file.
initialManifestInitial?Default animation and/or state machine to load on open.

ManifestInitial

PropertyTypeDescription
stateMachineString?ID of the state machine to load by default.
animationString?ID of the animation to load by default.

ManifestAnimation

PropertyTypeDescription
idStringAnimation identifier.
nameString?Display name.
initialThemeString?Default theme ID applied when this animation loads.
backgroundString?Background color.
themes[String]?IDs of themes compatible with this animation.

ManifestTheme

PropertyTypeDescription
idStringTheme identifier.
nameString?Display name.

ManifestStateMachine

PropertyTypeDescription
idStringState machine identifier.
nameString?Display name.

Layout

Controls how the animation fits and aligns within its view bounds.

PropertyTypeDefaultDescription
fitFit.containHow the animation scales: .contain, .cover, .fill, .fitWidth, .fitHeight, .none.
align[Float][0.5, 0.5]Alignment within bounds [x, y]. [0, 0] = top-left, [0.5, 0.5] = center, [1, 1] = bottom-right.
Last updated: April 10, 2026 at 9:12 AMEdit this page