RiveModel represents a Rive file and provides methods to access and configure artboards, animations, and state machines. It serves as the data layer between a Rive file and the view that renders it.
Initializers
Initialize with RiveFile
public init(riveFile: RiveFile)
An already loaded RiveFile instance
let riveFile = try RiveFile(name: "hero")
let model = RiveModel(riveFile: riveFile)
Initialize with File Name
public init(
fileName: String,
extension: String = ".riv",
in bundle: Bundle = .main,
loadCdn: Bool = true,
customLoader: LoadAsset? = nil
) throws
The name of the Rive file (without extension)
The bundle containing the Rive file
Whether to load assets from CDN
Custom asset loader for loading external assets
let model = try RiveModel(fileName: "hero")
Initialize with Web URL
public init(
webURL: String,
delegate: RiveFileDelegate,
loadCdn: Bool
)
The URL of the Rive file to load from the web
Delegate to receive callbacks when the file loads or errors
Whether to load assets from CDN
class MyDelegate: RiveFileDelegate {
func riveFileDidLoad(_ riveFile: RiveFile) throws {
print("File loaded")
}
func riveFileDidError(_ error: any Error) {
print("Error: \(error)")
}
}
let delegate = MyDelegate()
let model = RiveModel(webURL: "https://example.com/file.riv", delegate: delegate, loadCdn: true)
Properties
stateMachine
public internal(set) var stateMachine: RiveStateMachineInstance?
animation
public internal(set) var animation: RiveLinearAnimationInstance?
artboard
public private(set) var artboard: RiveArtboard!
riveFile
public private(set) var riveFile: RiveFile
volume
The volume of the current artboard, if available. Defaults to 1.0. Setting this value will update the artboard’s volume if an artboard is configured.
Example:
model.volume = 0.5 // Set volume to 50%
Methods
setArtboard (by name)
open func setArtboard(_ name: String) throws
The name of the artboard to set
RiveModelError.invalidArtboard if the artboard name is not found.
Example:
try model.setArtboard("Character")
setArtboard (by index or default)
open func setArtboard(_ index: Int? = nil) throws
The index of the artboard to set. Pass nil to use the default artboard
RiveModelError.invalidArtboard if the artboard is not found.
Example:
// Use default artboard
try model.setArtboard()
// Use artboard at index 0
try model.setArtboard(0)
setStateMachine (by name)
open func setStateMachine(_ name: String) throws
The name of the state machine to set
RiveModelError.invalidStateMachine if the state machine name is not found.
Example:
try model.setStateMachine("State Machine 1")
setStateMachine (by index or default)
open func setStateMachine(_ index: Int? = nil) throws
The index of the state machine to set. Pass nil to use the default state machine from the artboard, or index 0 as a fallback
RiveModelError.invalidStateMachine if the state machine is not found.
Example:
// Use default state machine
try model.setStateMachine()
// Use state machine at index 0
try model.setStateMachine(0)
setAnimation (by name)
open func setAnimation(_ name: String) throws
The name of the animation to set
RiveModelError.invalidAnimation if the animation name is not found.
Example:
try model.setAnimation("idle")
setAnimation (by index or default)
open func setAnimation(_ index: Int? = nil) throws
The index of the animation to set. Defaults to 0 if not provided
RiveModelError.invalidAnimation if the animation is not found.
Example:
// Use animation at index 0
try model.setAnimation()
// Use animation at index 1
try model.setAnimation(1)
enableAutoBind
open func enableAutoBind(_ callback: @escaping AutoBindCallback)
The callback to be called when a RiveDataBindingViewModel.Instance is bound to the current artboard and/or state machine
model.enableAutoBind { instance in
// Store strong reference
self.viewModelInstance = instance
// Update properties
instance.propertyController.set("username", value: "John")
}
disableAutoBind
open func disableAutoBind()
enableAutoBind.
Example:
Type Aliases
AutoBindCallback
public typealias AutoBindCallback = (RiveDataBindingViewModel.Instance) -> Void
Errors
RiveModelError
enum RiveModelError: Error {
case invalidStateMachine(_ message: String)
case invalidAnimation(_ message: String)
case invalidArtboard(_ message: String)
}
Usage Examples
Basic Model Setup
import RiveRuntime
// Create a model
let model = try RiveModel(fileName: "hero")
// Set artboard and animation
try model.setArtboard("MainArtboard")
try model.setAnimation("idle")
Working with State Machines
import RiveRuntime
let model = try RiveModel(fileName: "button")
// Set artboard and state machine
try model.setArtboard()
try model.setStateMachine("State Machine 1")
// Access state machine inputs
if let stateMachine = model.stateMachine {
let trigger = stateMachine.getTrigger("Press")
trigger.fire()
}
Loading from Web
import RiveRuntime
class MyController: RiveFileDelegate {
var model: RiveModel?
func loadAnimation() {
model = RiveModel(
webURL: "https://example.com/animation.riv",
delegate: self,
loadCdn: true
)
}
func riveFileDidLoad(_ riveFile: RiveFile) throws {
print("File loaded successfully")
try model?.setArtboard()
try model?.setAnimation()
}
func riveFileDidError(_ error: any Error) {
print("Error loading file: \(error)")
}
}
Volume Control
import RiveRuntime
let model = try RiveModel(fileName: "audio_demo")
try model.setArtboard()
// Set volume to 50%
model.volume = 0.5
// Mute
model.volume = 0.0
// Full volume
model.volume = 1.0
Data Binding
import RiveRuntime
class MyViewController: UIViewController {
var model: RiveModel?
var viewModelInstance: RiveDataBindingViewModel.Instance?
func setupModel() {
model = try? RiveModel(fileName: "data_binding_demo")
model?.enableAutoBind { [weak self] instance in
self?.viewModelInstance = instance
// Set initial values
instance.propertyController.set("username", value: "Guest")
instance.propertyController.set("score", value: 0)
}
try? model?.setArtboard()
try? model?.setStateMachine()
}
func updateScore(_ newScore: Int) {
viewModelInstance?.propertyController.set("score", value: newScore)
}
}