RiveViewModel - Rive iOS Runtime

RiveViewModel is the main class for controlling a RiveView. For most common Rive files, you should only need to interact with a RiveViewModel object.

Usage Guidelines

Initialize with either an Animation name or a StateMachine name, but not both
Only one will be used; if both are given, the StateMachine takes precedence
Default StateMachine or Animation from the file can be used by leaving their parameters nil

Initializers

Initialize with RiveModel and State Machine

public init(
    _ model: RiveModel,
    stateMachineName: String?,
    fit: RiveFit = .contain,
    alignment: RiveAlignment = .center,
    autoPlay: Bool = true,
    artboardName: String? = nil
)

model

RiveModel

required

The RiveModel instance containing the Rive file data

stateMachineName

String?

required

The name of the state machine to use. Pass nil to use the default state machine

fit

RiveFit

default:".contain"

How the Rive content should fit within the view bounds

alignment

RiveAlignment

default:".center"

How the Rive content should align within the view bounds

autoPlay

Bool

default:"true"

Whether the animation or state machine should start playing automatically

artboardName

String?

The name of the artboard to use. Pass nil to use the default artboard

Initialize with RiveModel and Animation

public init(
    _ model: RiveModel,
    animationName: String? = nil,
    fit: RiveFit = .contain,
    alignment: RiveAlignment = .center,
    autoPlay: Bool = true,
    artboardName: String? = nil
)

model

RiveModel

required

The RiveModel instance containing the Rive file data

animationName

String?

The name of the animation to play. Pass nil to use the default animation

fit

RiveFit

default:".contain"

How the Rive content should fit within the view bounds

alignment

RiveAlignment

default:".center"

How the Rive content should align within the view bounds

autoPlay

Bool

default:"true"

Whether the animation should start playing automatically

artboardName

String?

The name of the artboard to use. Pass nil to use the default artboard

Initialize with File Name and State Machine

public init(
    fileName: String,
    extension: String = ".riv",
    in bundle: Bundle = .main,
    stateMachineName: String?,
    fit: RiveFit = .contain,
    alignment: RiveAlignment = .center,
    autoPlay: Bool = true,
    artboardName: String? = nil,
    loadCdn: Bool = true,
    customLoader: LoadAsset? = nil
)

fileName

String

required

The name of the Rive file (without extension)

extension

String

default:".riv"

The file extension

bundle

Bundle

default:".main"

The bundle containing the Rive file

stateMachineName

String?

required

The name of the state machine to use. Pass nil to use the default state machine

fit

RiveFit

default:".contain"

How the Rive content should fit within the view bounds

alignment

RiveAlignment

default:".center"

How the Rive content should align within the view bounds

autoPlay

Bool

default:"true"

Whether the state machine should start playing automatically

artboardName

String?

The name of the artboard to use. Pass nil to use the default artboard

loadCdn

Bool

default:"true"

Whether to load assets from CDN

customLoader

LoadAsset?

Custom asset loader for loading external assets

Initialize with File Name and Animation

public init(
    fileName: String,
    extension: String = ".riv",
    in bundle: Bundle = .main,
    animationName: String? = nil,
    fit: RiveFit = .contain,
    alignment: RiveAlignment = .center,
    autoPlay: Bool = true,
    artboardName: String? = nil,
    preferredFramesPerSecond: Int? = nil,
    loadCdn: Bool = true,
    customLoader: LoadAsset? = nil
)

fileName

String

required

The name of the Rive file (without extension)

extension

String

default:".riv"

The file extension

bundle

Bundle

default:".main"

The bundle containing the Rive file

animationName

String?

The name of the animation to play. Pass nil to use the default animation

fit

RiveFit

default:".contain"

How the Rive content should fit within the view bounds

alignment

RiveAlignment

default:".center"

How the Rive content should align within the view bounds

autoPlay

Bool

default:"true"

Whether the animation should start playing automatically

artboardName

String?

The name of the artboard to use. Pass nil to use the default artboard

preferredFramesPerSecond

Int?

Preferred frames per second for the animation

loadCdn

Bool

default:"true"

Whether to load assets from CDN

customLoader

LoadAsset?

Custom asset loader for loading external assets

Initialize with Web URL and State Machine

public init(
    webURL: String,
    stateMachineName: String?,
    fit: RiveFit = .contain,
    alignment: RiveAlignment = .center,
    autoPlay: Bool = true,
    loadCdn: Bool = true,
    artboardName: String? = nil
)

webURL

String

required

The URL of the Rive file to load from the web

stateMachineName

String?

required

The name of the state machine to use. Pass nil to use the default state machine

fit

RiveFit

default:".contain"

How the Rive content should fit within the view bounds

alignment

RiveAlignment

default:".center"

How the Rive content should align within the view bounds

autoPlay

Bool

default:"true"

Whether the state machine should start playing automatically

loadCdn

Bool

default:"true"

Whether to load assets from CDN

artboardName

String?

The name of the artboard to use. Pass nil to use the default artboard

Initialize with Web URL and Animation

public init(
    webURL: String,
    animationName: String? = nil,
    fit: RiveFit = .contain,
    alignment: RiveAlignment = .center,
    autoPlay: Bool = true,
    loadCdn: Bool = true,
    artboardName: String? = nil
)

webURL

String

required

The URL of the Rive file to load from the web

animationName

String?

The name of the animation to play. Pass nil to use the default animation

fit

RiveFit

default:".contain"

How the Rive content should fit within the view bounds

alignment

RiveAlignment

default:".center"

How the Rive content should align within the view bounds

autoPlay

Bool

default:"true"

Whether the animation should start playing automatically

loadCdn

Bool

default:"true"

Whether to load assets from CDN

artboardName

String?

The name of the artboard to use. Pass nil to use the default artboard

Properties

riveModel

open private(set) var riveModel: RiveModel?

The underlying RiveModel instance. Read-only.

isPlaying

open var isPlaying: Bool { get }

Returns true if the animation or state machine is currently playing.

autoPlay

open var autoPlay: Bool

Whether the animation or state machine should start playing automatically when loaded.

fit

open var fit: RiveFit

How the Rive content should fit within the view bounds. Defaults to .contain.

alignment

open var alignment: RiveAlignment

How the Rive content should align within the view bounds. Defaults to .center.

layoutScaleFactor

open var layoutScaleFactor: Double

The scale factor to apply when using the layout fit. By default, this value is -1, where Rive will determine the correct scale for your device. To override this default behavior, set this value to a value greater than 0.

If the scale factor is less than or equal to 0, nothing will be drawn.

forwardsListenerEvents

open var forwardsListenerEvents: Bool

Sets whether the current Rive view should forward Rive listener touch/click events to any next responders. When true, touch/click events will be forwarded to any next responder(s). When false, only the Rive view will handle touch/click events. Defaults to false.

On iOS, this is handled separately from isExclusiveTouch.

layoutScaleFactorAutomatic

public static let layoutScaleFactorAutomatic: Double

The default layout scale factor that allows for the scale factor to be determined by Rive.

Methods

play

open func play(
    animationName: String? = nil,
    loop: RiveLoop = .autoLoop,
    direction: RiveDirection = .autoDirection
)

Starts the active Animation or StateMachine from its last position. It will start from the beginning if the active Animation has ended or a new one is provided.

animationName

String?

The name of a new Animation to play on the current Artboard

loop

RiveLoop

default:".autoLoop"

The loop mode for the active Animation

direction

RiveDirection

default:".autoDirection"

The playback direction for the active Animation

Example:

let viewModel = RiveViewModel(fileName: "hero")
viewModel.play(animationName: "idle", loop: .loop)

pause

open func pause()

Halts the active Animation or StateMachine and will resume from its current position when next played. Example:

viewModel.pause()

stop

open func stop()

Halts the active Animation or StateMachine and sets it at its starting position. Example:

viewModel.stop()

reset

open func reset()

Sets the active Animation or StateMachine back to their starting position. Example:

viewModel.reset()

configureModel

open func configureModel(
    artboardName: String? = nil,
    stateMachineName: String? = nil,
    animationName: String? = nil
) throws

Instantiates elements in the model needed to play in a RiveView.

artboardName

String?

The name of the artboard to configure. Pass nil to use the current or default artboard

stateMachineName

String?

The name of the state machine to configure. Pass nil to use default

animationName

String?

The name of the animation to configure. Pass nil to use default

Example:

try viewModel.configureModel(artboardName: "Character", stateMachineName: "State Machine 1")

resetToDefaultModel

open func resetToDefaultModel()

Sets the Artboard, StateMachine or Animation back to the first one given to the RiveViewModel. Example:

viewModel.resetToDefaultModel()

triggerInput

open func triggerInput(_ inputName: String)

Provide the active StateMachine a Trigger input.

inputName

String

required

The name of a Trigger input on the active StateMachine

Example:

viewModel.triggerInput("Button")

triggerInput (with path)

open func triggerInput(_ inputName: String, path: String)

Provide the specified nested Artboard with a Trigger input.

inputName

String

required

The name of a Trigger input on the active StateMachine

path

String

required

A String representing the path to the nested artboard delimited by ”/” (e.g., “Nested” or “Level1/Level2/Level3”)

Example:

viewModel.triggerInput("Button", path: "Character/Head")

setInput (Boolean)

open func setInput(_ inputName: String, value: Bool)

Provide the active StateMachine a Boolean input.

inputName

String

required

The name of a Boolean input on the active StateMachine

value

Bool

required

A Bool value for the input

Example:

viewModel.setInput("isActive", value: true)

setInput (Boolean with path)

open func setInput(_ inputName: String, value: Bool, path: String)

Provide the specified nested Artboard with a Boolean input.

inputName

String

required

The name of a Boolean input on the active StateMachine

value

Bool

required

A Bool value for the input

path

String

required

A String representing the path to the nested artboard delimited by ”/”

Example:

viewModel.setInput("isActive", value: true, path: "Character")

setInput (Float)

open func setInput(_ inputName: String, value: Float)

Provide the active StateMachine a Number input.

inputName

String

required

The name of a Number input on the active StateMachine

value

Float

required

A Float value for the input

Example:

viewModel.setInput("progress", value: 0.75)

setInput (Float with path)

open func setInput(_ inputName: String, value: Float, path: String)

Provide the specified nested Artboard with a Number input.

inputName

String

required

The name of a Number input on the active StateMachine

value

Float

required

A Float value for the input

path

String

required

A String representing the path to the nested artboard delimited by ”/”

Example:

viewModel.setInput("progress", value: 0.75, path: "Character")

setInput (Double)

open func setInput(_ inputName: String, value: Double)

Provide the active StateMachine a Number input.

inputName

String

required

The name of a Number input on the active StateMachine

value

Double

required

A Double value for the input

Example:

viewModel.setInput("progress", value: 0.75)

setInput (Double with path)

open func setInput(_ inputName: String, value: Double, path: String)

Provide the specified nested Artboard with a Number input.

inputName

String

required

The name of a Number input on the active StateMachine

value

Double

required

A Double value for the input

path

String

required

A String representing the path to the nested artboard delimited by ”/”

Example:

viewModel.setInput("progress", value: 0.75, path: "Character")

boolInput

open func boolInput(named name: String) -> RiveSMIBool?

Returns the current boolean input by name. Get its value by calling .value on the returned object.

name

String

required

The name of the input

Returns: The boolean input if it exists. Returns nil if the input cannot be found. Example:

if let input = viewModel.boolInput(named: "isActive") {
    print("Current value: \(input.value)")
}

numberInput

open func numberInput(named name: String) -> RiveSMINumber?

Returns the current number input by name. Get its value by calling .value on the returned object.

name

String

required

The name of the input

Returns: The number input if it exists. Returns nil if the input cannot be found. Example:

if let input = viewModel.numberInput(named: "progress") {
    print("Current value: \(input.value)")
}

getTextRunValue

open func getTextRunValue(_ textRunName: String) -> String?

Get a text value from a specified text run.

textRunName

String

required

The name of a Text Run on the active Artboard

Returns: String text value of the specified text run if applicable. Example:

if let text = viewModel.getTextRunValue("TitleText") {
    print("Text: \(text)")
}

getTextRunValue (with path)

open func getTextRunValue(_ textRunName: String, path: String) -> String?

Get a text value from a specified text run in a nested artboard.

textRunName

String

required

The name of a Text Run on the active Artboard

path

String

required

The path to the nested text run

Returns: String text value of the specified text run if applicable. Example:

if let text = viewModel.getTextRunValue("TitleText", path: "Character/Head") {
    print("Text: \(text)")
}

setTextRunValue

open func setTextRunValue(_ textRunName: String, textValue: String) throws

Set a text value for a specified text run.

textRunName

String

required

The name of a Text Run on the active Artboard

textValue

String

required

A String value for the text run

Example:

try viewModel.setTextRunValue("TitleText", textValue: "Hello, World!")

setTextRunValue (with path)

open func setTextRunValue(
    _ textRunName: String,
    path: String,
    textValue: String
) throws

Set a text value for a specified text run in a nested artboard.

textRunName

String

required

The name of a Text Run on the active Artboard

path

String

required

The path to the nested text run

textValue

String

required

A String value for the text run

If the specified path is empty, the parent artboard will be used to find the text run.

Example:

try viewModel.setTextRunValue("TitleText", path: "Character", textValue: "Hello!")

artboardNames

open func artboardNames() -> [String]

Returns an array of all artboard names in the Rive file. Example:

let names = viewModel.artboardNames()
print("Available artboards: \(names)")

setPreferredFramesPerSecond

open func setPreferredFramesPerSecond(preferredFramesPerSecond: Int)

Hints to underlying CADisplayLink in RiveView the preferred FPS to run at.

preferredFramesPerSecond

Int

required

Integer number of seconds to set preferred FPS at

Example:

viewModel.setPreferredFramesPerSecond(preferredFramesPerSecond: 60)

setPreferredFrameRateRange

@available(iOS 15.0, tvOS 15.0, visionOS 1.0, macOS 14, *)
open func setPreferredFrameRateRange(preferredFrameRateRange: CAFrameRateRange)

Hints to underlying CADisplayLink in RiveView the preferred frame rate range.

preferredFrameRateRange

CAFrameRateRange

required

Frame rate range to set

Example:

if #available(iOS 15.0, *) {
    let range = CAFrameRateRange(minimum: 60, maximum: 120, preferred: 120)
    viewModel.setPreferredFrameRateRange(preferredFrameRateRange: range)
}

createRiveView

open func createRiveView() -> RiveView

Makes a new RiveView for the instance property with data from model which will replace any previous RiveView. This is called when first drawing a RiveViewRepresentable. Returns: Reference to the new view that the RiveViewModel will be maintaining. Example:

let riveView = viewModel.createRiveView()

setRiveView

open func setRiveView(view: RiveView)

Registers a RiveView with this view model.

view

RiveView

required

The RiveView to register

Example:

viewModel.setRiveView(view: riveView)

update

open func update(view: RiveView)

Gives updated layout values to the provided RiveView. This is called in the process of re-displaying RiveViewRepresentable.

view

RiveView

required

The RiveView that will be updated

Example:

viewModel.update(view: riveView)

deregisterView

open func deregisterView()

Stops maintaining a connection to any RiveView. Example:

viewModel.deregisterView()

view

open func view() -> AnyView

Creates a SwiftUI view that can be added to the body of a SwiftUI View. Returns: A SwiftUI AnyView wrapping the RiveView. Example:

struct ContentView: View {
    let viewModel = RiveViewModel(fileName: "hero")
    
    var body: some View {
        viewModel.view()
    }
}

setView

open func setView(_ view: RiveView)

This can be used to connect with and configure an RiveView that was created elsewhere. Does not need to be called when updating an already configured RiveView. Useful for attaching views created in a UIViewController or Storyboard.

view

RiveView

required

The RiveView that this RiveViewModel will maintain

Example (UIKit):

class AnimationViewController: UIViewController {
    @IBOutlet weak var riveView: RiveView!
    var viewModel = RiveViewModel(fileName: "hero")
    
    override func viewDidLoad() {
        viewModel.setView(riveView)
    }
}

Delegate Methods

The following delegate methods can be implemented by conforming to RiveFileDelegate, RiveStateMachineDelegate, and RivePlayerDelegate:

riveFileDidLoad

open func riveFileDidLoad(_ riveFile: RiveFile) throws

Called by RiveFile when it finishes downloading an asset asynchronously.

riveFileDidError

open func riveFileDidError(_ error: any Error)

Called when there is an error loading the Rive file.

player (played)

open func player(playedWithModel riveModel: RiveModel?)

Called when playback starts.

player (paused)

open func player(pausedWithModel riveModel: RiveModel?)

Called when playback pauses.

player (looped)

open func player(loopedWithModel riveModel: RiveModel?, type: Int)

Called when an animation loops.

player (stopped)

open func player(stoppedWithModel riveModel: RiveModel?)

Called when playback stops.

player (didAdvanceby)

open func player(didAdvanceby seconds: Double, riveModel: RiveModel?)

Called on each frame advance with the elapsed time.

Usage Examples

SwiftUI Example

import SwiftUI
import RiveRuntime

struct AnimationView: View {
    var body: some View {
        RiveViewModel(fileName: "hero").view()
    }
}

UIKit Example

import UIKit
import RiveRuntime

class AnimationViewController: UIViewController {
    @IBOutlet weak var riveView: RiveView!
    var viewModel = RiveViewModel(fileName: "hero")
    
    override func viewDidLoad() {
        viewModel.setView(riveView)
    }
}

Interactive State Machine Example

import SwiftUI
import RiveRuntime

struct InteractiveView: View {
    let viewModel = RiveViewModel(
        fileName: "button",
        stateMachineName: "State Machine 1"
    )
    
    var body: some View {
        VStack {
            viewModel.view()
            
            Button("Trigger") {
                viewModel.triggerInput("Press")
            }
        }
    }
}

High-Level API

Core Classes

State Machine Inputs

Data Binding

Supporting Types

​Usage Guidelines

​Initializers

​Initialize with RiveModel and State Machine

​Initialize with RiveModel and Animation

​Initialize with File Name and State Machine

​Initialize with File Name and Animation

​Initialize with Web URL and State Machine

​Initialize with Web URL and Animation

​Properties

​riveModel

​isPlaying

​autoPlay

​fit

​alignment

​layoutScaleFactor

​forwardsListenerEvents

​layoutScaleFactorAutomatic

​Methods

​play

​pause

​stop

​reset

​configureModel

​resetToDefaultModel

​triggerInput

​triggerInput (with path)

​setInput (Boolean)

​setInput (Boolean with path)

​setInput (Float)

​setInput (Float with path)

​setInput (Double)

​setInput (Double with path)

​boolInput

​numberInput

​getTextRunValue

​getTextRunValue (with path)

​setTextRunValue

​setTextRunValue (with path)

​artboardNames

​setPreferredFramesPerSecond

​setPreferredFrameRateRange

​createRiveView

​setRiveView

​update

​deregisterView

​view

​setView

​Delegate Methods

​riveFileDidLoad

​riveFileDidError

​player (played)

​player (paused)

​player (looped)

​player (stopped)

​player (didAdvanceby)

​Usage Examples

​SwiftUI Example

​UIKit Example

​Interactive State Machine Example

Build docs developers (and LLMs) love

Usage Guidelines

Initializers

Initialize with RiveModel and State Machine

Initialize with RiveModel and Animation

Initialize with File Name and State Machine

Initialize with File Name and Animation

Initialize with Web URL and State Machine

Initialize with Web URL and Animation

Properties

riveModel

isPlaying

autoPlay

fit

alignment

layoutScaleFactor

forwardsListenerEvents

layoutScaleFactorAutomatic

Methods

play

pause

stop

reset

configureModel

resetToDefaultModel

triggerInput

triggerInput (with path)

setInput (Boolean)

setInput (Boolean with path)

setInput (Float)

setInput (Float with path)

setInput (Double)

setInput (Double with path)

boolInput

numberInput

getTextRunValue

getTextRunValue (with path)

setTextRunValue

setTextRunValue (with path)

artboardNames

setPreferredFramesPerSecond

setPreferredFrameRateRange

createRiveView

setRiveView

update

deregisterView

view

setView

Delegate Methods

riveFileDidLoad

riveFileDidError

player (played)

player (paused)

player (looped)

player (stopped)

player (didAdvanceby)

Usage Examples

SwiftUI Example

UIKit Example

Interactive State Machine Example