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
| Initializer | Description |
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.
| Modifier | Description |
.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
| Initializer | Description |
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
| Property | Type | Description |
dotLottieAnimation | DotLottieAnimation | The underlying animation instance. |
config | AnimationConfig | The current animation configuration. |
isAnimationPlaying | Bool | Whether the animation is currently playing. |
isAnimationPaused | Bool | Whether the animation is currently paused. |
isAnimationStopped | Bool | Whether the animation is currently stopped. |
loopMode | DotLottieLoopMode | The current loop mode (.playOnce or .loop). |
animationSpeed | Float | The current playback speed multiplier. |
currentProgress | Float | The current playback progress (0.0–1.0). |
currentFrame | Float | The current frame number. |
totalFrames | Float | The total number of frames. |
duration | Float | The total animation duration in milliseconds. |
mode | Mode | The current playback mode. |
useFrameInterpolation | Bool | Whether frame interpolation is enabled. |
segments | (Float, Float) | The current playback segment range. |
animationLoaded | (() -> Void)? | Callback invoked when the animation finishes loading. |
Playback Methods
| Method | Return Type | Description |
play() | Void | Begin playback. |
pause() | Void | Pause playback. |
stop() | Void | Stop playback and reset to the initial frame. |
play(fromProgress:toProgress:loopMode:) | Void | Play between two progress values with an optional loop mode. |
play(fromFrame:toFrame:loopMode:) | Void | Play between two frame numbers with an optional loop mode. |
play(marker:loopMode:) | Void | Play a named marker segment with an optional loop mode. |
play(fromMarker:toMarker:loopMode:) | Void | Play between two named markers with an optional loop mode. |
setFrame(_:) | Void | Seek to a specific frame. |
setProgress(_:) | Void | Seek to a specific progress value (0.0–1.0). |
Marker Methods
| Method | Return Type | Description |
markers() | [Marker] | Returns all markers in the animation. |
setMarker(_:) | Void | Set 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
| Method | Return Type | Description |
loadAnimation(byId:) | Void | Load a specific animation by ID from a multi-animation .lottie file. |
manifest() | Manifest? | Returns the .lottie file manifest. |
State Machine Methods
| Method | Return Type | Description |
isStateMachine() | Bool | Returns whether a state machine is active. |
startStateMachine(id:openUrlPolicy:) | Void | Load and start a state machine by ID. |
stateMachineLoad(id:) | Bool | Load a state machine by ID. |
stateMachineLoadData(_:) | Bool | Load a state machine from a JSON string. |
stateMachineStart() | Bool | Start the loaded state machine. |
stateMachineStop() | Bool | Stop the active state machine. |
stateMachinePostEvent(_:force:) | Void | Post a typed Event to the state machine. |
stateMachinePostClickEvent(at:) | Void | Post a click event at a position. |
stateMachinePostPointerDownEvent(at:) | Void | Post a pointer down event at a position. |
stateMachinePostPointerUpEvent(at:) | Void | Post a pointer up event at a position. |
stateMachinePostPointerMoveEvent(at:) | Void | Post a pointer move event at a position. |
stateMachinePostPointerEnterEvent(at:) | Void | Post a pointer enter event at a position. |
stateMachinePostPointerExitEvent(at:) | Void | Post a pointer exit event at a position. |
stateMachineCurrentState() | String | Returns 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:) | Void | Set a numeric input value. |
stateMachineSetBooleanInput(key:value:) | Void | Set a boolean input value. |
stateMachineSetStringInput(key:value:) | Void | Set 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(_:) | Void | Subscribe a StateMachineObserver. |
stateMachineUnsubscribe(_:) | Void | Unsubscribe 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
| Initializer | Description |
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.
| Property | Type | Default | Description |
autoplay | Bool | false | Autoplay the animation on load. |
loop | Bool | false | Loop the animation. |
speed | Float | 1.0 | Playback speed multiplier. |
mode | Mode | .forward | Playback mode: forward, reverse, bounce, bounceReverse. |
width | Int | 512 | Override animation width. |
height | Int | 512 | Override animation height. |
segment | (Float, Float) | — | Play between an interval of frames. |
backgroundColor | CIImage | — | Background color of the animation canvas. |
useFrameInterpolation | Bool | true | Interpolate between frames. Useful for smooth playback at slow speeds. |
marker | String | — | Named marker to play on load. |
layout | Layout | — | Animation layout configuration. See Layout Configuration. |
themeId | String | — | Theme ID to apply on load. |
loopCount | Int? | 0 | Number of times to loop. 0 means infinite when loop is true. |
animationId | String? | "" | Animation ID for multi-animation .lottie files. |
stateMachineId | String? | "" | State machine ID to auto-load on initialization. |
Properties
| Property | Type | Description |
currentFrame() | Float | The currently displayed frame number. |
duration() | Float | Total playback time in milliseconds. |
totalFrames() | Float | Total number of frames. |
loop() | Bool | Whether looping is enabled. |
speed() | Float | Current playback speed multiplier. |
loopCount() | Int | Number of completed loops. |
mode() | Mode | Current playback mode. |
isPaused() | Bool | Whether the animation is paused. |
isStopped() | Bool | Whether the animation is stopped. |
isPlaying() | Bool | Whether the animation is playing. |
isLoaded() | Bool | Whether the animation has loaded successfully. |
error() | Bool | Whether the animation has errored. |
errorMessage() | String | Error message string, if any. |
manifest() | Manifest | The .lottie manifest. |
segment() | (Float, Float) | Current playback segment. |
backgroundColor() | CIImage | Current background color. |
autoplay() | Bool | Whether autoplay is enabled. |
useFrameInterpolation() | Bool | Whether frame interpolation is enabled. |
currentProgress() | Float | Current playback progress (0.0–1.0). |
markers() | [Marker] | Markers in the animation. See Marker. |
Playback Methods
| Method | Return Type | Description |
play() | Bool | Begin playback from the current position. |
pause() | Bool | Pause without resetting position. |
stop() | Bool | Stop and return to the initial frame. |
play(fromFrame:) | Bool | Start playback from a specific frame. |
play(fromProgress:) | Bool | Start playback from a specific progress value (0.0–1.0). |
setFrame(frame:) | Bool | Seek to a specific frame. |
setProgress(progress:) | Bool | Seek to a specific progress value (0.0–1.0). |
setSpeed(speed:) | Void | Set the playback speed multiplier. |
setLoop(loop:) | Void | Enable or disable looping. |
setMode(mode:) | Void | Set the playback mode. |
setMarker(marker:) | Void | Set the active marker for playback. |
setSegments(segments:) | Void | Set the start and end frame range. |
setAutoplay(autoplay:) | Void | Enable or disable autoplay. |
setFrameInterpolation(_:) | Void | Enable or disable frame interpolation. |
setBackgroundColor(bgColor:) | Void | Set the background color. |
resize(width:height:) | Void | Manually resize the animation canvas. |
render() | Bool | Force a render of the current frame. |
tick() | Void | Request 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
| Method | Return Type | Description |
loadAnimation(animationId:) | Void | Load a specific animation by ID from the manifest. |
Theming & Slots
| Method | Return Type | Description |
setTheme(_:) | Bool | Apply a theme by ID. |
setThemeData(_:) | Bool | Apply theme data from a JSON string. |
resetTheme() | Bool | Remove the applied theme. |
activeThemeId() | String | Get the active theme ID. |
setSlots(_:) | Bool | Apply slot data from a JSON string. |
clearSlots() | Bool | Clear all slots. |
clearSlot(slotId:) | Bool | Clear a specific slot. |
setColorSlot(slotId:r:g:b:) | Bool | Set a color slot with RGB values (0.0–1.0). |
setScalarSlot(slotId:value:) | Bool | Set a scalar slot value. |
setTextSlot(slotId:text:) | Bool | Set a text slot value. |
setVectorSlot(slotId:x:y:) | Bool | Set a vector slot value. |
setPositionSlot(slotId:x:y:) | Bool | Set a position slot value. |
setImageSlotPath(slotId:path:) | Bool | Set an image slot from a file path. |
setImageSlotDataUrl(slotId:dataUrl:) | Bool | Set an image slot from a data URL. |
Observer Methods
| Method | Return Type | Description |
subscribe(observer:) | Void | Subscribe an Observer to animation events. |
unsubscribe(observer:) | Void | Unsubscribe an Observer. |
State Machine Methods
| Method | Return Type | Description |
stateMachineLoad(id:) | Bool | Load a state machine by ID from the manifest. |
stateMachineLoadData(_:) | Bool | Load a state machine from a JSON string. |
stateMachineStart(openUrlPolicy:) | Bool | Start the loaded state machine. |
stateMachineStart(id:openUrlPolicy:) | Bool | Load and start a state machine in one call. |
stateMachineStop() | Bool | Stop the active state machine. |
stateMachineCurrentState() | String | Get the name of the current state. |
getStateMachine(id:) | String | Get a state machine definition JSON by ID. |
stateMachinePostEvent(_:force:) | Void | Post a typed Event to the state machine. |
stateMachineFire(event:) | Bool | Fire a named event string. |
stateMachineSubscribe(observer:) | Void | Subscribe a StateMachineObserver. |
stateMachineUnsubscribe(observer:) | Void | Unsubscribe a StateMachineObserver. |
stateMachineFrameworkSetup() | [String] | Get framework setup requirements. |
stateMachineGetInputs() | [String: String] | Get all inputs and their current values. |
stateMachineSetBooleanInput(key:value:) | Void | Set a boolean input. |
stateMachineSetNumericInput(key:value:) | Void | Set a numeric input. |
stateMachineSetStringInput(key:value:) | Void | Set 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
| Property | Type | Description |
generator | String? | Tool that generated the .lottie file. |
version | String? | 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. |
initial | ManifestInitial? | Default animation and/or state machine to load on open. |
ManifestInitial
| Property | Type | Description |
stateMachine | String? | ID of the state machine to load by default. |
animation | String? | ID of the animation to load by default. |
ManifestAnimation
| Property | Type | Description |
id | String | Animation identifier. |
name | String? | Display name. |
initialTheme | String? | Default theme ID applied when this animation loads. |
background | String? | Background color. |
themes | [String]? | IDs of themes compatible with this animation. |
ManifestTheme
| Property | Type | Description |
id | String | Theme identifier. |
name | String? | Display name. |
ManifestStateMachine
| Property | Type | Description |
id | String | State machine identifier. |
name | String? | Display name. |
Layout
Controls how the animation fits and aligns within its view bounds.
| Property | Type | Default | Description |
fit | Fit | .contain | How 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. |