Overview

Before engaging with the runtime data binding APIs, it is important to familiarize yourself with the core concepts presented in the Overview.

Data Binding Concepts

An overview of core data binding concepts.

View Models

View models describe a set of properties, but cannot themselves be used to get or set values - that is the role of view model instances.

To begin, we need to get a reference to a particular view model. This can be done either by index, by name, or the default for a given artboard, and is done from the Rive file. The default option refers to the view model assigned to an artboard by the dropdown in the editor.

Access a View Model from the created Rive object in the onLoad callback:

const rive = new rive.Rive({
    onLoad: () => {
        // The Rive object is now loaded and ready to use.
    }
});

Once Rive is loaded, you can access the view models using the following methods:

// Get reference by name
const namedVM = rive.viewModelByName("My View Model");

// Get reference by index
for (let i = 0; i < rive.viewModelCount(); i++) {
    const indexedVM = rive.viewModelByIndex(i);
}

// Get reference to the default view model
const defaultVM = rive.defaultViewModel();

Alternatively, if you have access to the underlying Rive File object you can access the above methods on the file.

const namedVM = file.viewModelByName("My View Model");
const indexedVM = file.viewModelByIndex(0);
const defaultVM = file.defaultArtboardViewModel(artboard);

Access a View Model from the created Rive object in the onLoad callback:

const rive = new rive.Rive({
    onLoad: () => {
        // The Rive object is now loaded and ready to use.
    }
});

Once Rive is loaded, you can access the view models using the following methods:

// Get reference by name
const namedVM = rive.viewModelByName("My View Model");

// Get reference by index
for (let i = 0; i < rive.viewModelCount(); i++) {
    const indexedVM = rive.viewModelByIndex(i);
}

// Get reference to the default view model
const defaultVM = rive.defaultViewModel();

Alternatively, if you have access to the underlying Rive File object you can access the above methods on the file.

const namedVM = file.viewModelByName("My View Model");
const indexedVM = file.viewModelByIndex(0);
const defaultVM = file.defaultArtboardViewModel(artboard);

let riveViewModel = RiveViewModel(...)
let file = riveViewModel.riveModel!.riveFile

// Data binding view model by name
let viewModelByName = file.viewModelNamed("...")

// Data binding view model by index
for index in 0..<file.viewModelCount {
    let viewModelByIndex = file.viewModel(at: index)
}

// Default data binding view model for an artboard
let artboard = riveViewModel.riveModel!.artboard
let viewModelForArtboard = file.viewModel(for: artboard)

// `view` of type RiveAnimationView
view.setRiveResource(R.raw.my_rive_file)
val file = view.controller.file!!

// Get reference by name
val vm = file.getViewModelByName("My View Model")

// Get reference by index
for (i in 0 until file.viewModelCount) {
    val indexedVM = file.getViewModelByIndex(i)
}

// Get reference to the default view model
val defaultVM = file.defaultViewModelForArtboard(view.controller.activeArtboard!!)

// Get reference to the File and Artboard
final file = await File.asset(
    'assets/my_file.riv',
    riveFactory: Factory.rive,
);
final artboard = file!.defaultArtboard()!;

// Get reference by name
file.viewModelByName("My View Model");

// Get reference by index
for (var i = 0; i < file.viewModelCount; i++) {
    final indexedVM = file.viewModelByIndex(i);
}

// Get reference to the default view model for an artboard
final defaultVM = file.defaultArtboardViewModel(artboard);

// Dispose the view model when you're no longer using it
viewModel.dispose();

These APIs are only needed when the Data Binding Mode on the RiveWidget is set to Manual.

Otherwise, you can configure view model binding directly in the Unity Inspector under the Data section.

private void OnEnable()
{
    riveWidget.OnWidgetStatusChanged += HandleWidgetStatusChanged;
}

private void OnDisable()
{
    riveWidget.OnWidgetStatusChanged -= HandleWidgetStatusChanged;
}

private void HandleWidgetStatusChanged()
{
    if (riveWidget.Status == WidgetStatus.Loaded)
    {
        File file = riveWidget.File;

        // Get reference by name
        ViewModel viewModel = file.GetViewModelByName("My View Model");

        // Get reference by index
        for (int i = 0; i < file.ViewModelCount; i++)
        {
            ViewModel indexedVM = file.GetViewModelAtIndex(i);
        }

        // Get reference to the default view model for an artboard
        ViewModel defaultVM = riveWidget.Artboard.ViewModel;
    }
}

View Model Instances

Once we have a reference to a view model, it can be used to create an instance. When creating an instance, you have four options:

Create a blank instance - Fill the properties of the created instance with default values as follows:

Type Value
Number 0
String Empty string
Boolean False
Color #000000FF
Trigger Untriggered
Enum The first value
Nested view model Null
Create the default instance - Use the instance labelled “Default” in the editor. Usually this is the one a designer intends as the primary one to be used at runtime.
Create by index - Using the order returned when iterating over all available instances. Useful when creating multiple instances by iteration.
Create by name - Use the editor’s instance name. Useful when creating a specific instance.

Type	Value
Number	0
String	Empty string
Boolean	False
Color	#000000FF
Trigger	Untriggered
Enum	The first value
Nested view model	Null

// Create a blank instance from a view model (ViewModel)
const vmiBlank = viewModel.instance();

// Create a default instance from a view model (ViewModel)
const vmiDefault = viewModel.defaultInstance();

// Create an instance by index from a view model (ViewModel)
for (let i = 0; i < viewModel.instanceCount; i++) {
    const vmiIndexed = viewModel.instanceByIndex(i);
}

// Create an instace by name from a view model (ViewModel)
const vmiNamed = viewModel.instanceByName("My Instance");

// Create a blank instance from a view model (ViewModel)
const vmiBlank = viewModel.instance();

// Create a default instance from a view model (ViewModel)
const vmiDefault = viewModel.defaultInstance();

// Create an instance by index from a view model (ViewModel)
for (let i = 0; i < viewModel.instanceCount; i++) {
    const vmiIndexed = viewModel.instanceByIndex(i);
}

// Create an instace by name from a view model (ViewModel)
const vmiNamed = viewModel.instanceByName("My Instance");

    let riveViewModel = RiveViewModel(...)
    let viewModel = riveViewModel.riveModel!.riveFile.viewModelNamed("...")!
    
    // Create blank
    let blankInstance = viewModel.createInstance()

    // Create default
    let defaultInstance = viewModel.createDefaultInstance()

    // Create by index
    for index in 0..<viewModel.instanceCount {
        let instanceByIndex = viewModel.createInstance(fromIndex: index)
    }

    // Create by name
    for name in viewModel.instanceNames {
        let instanceByName = viewModel.createInstance(fromName: name)
    }

val vm = view.controller.file?.getViewModelByName("My View Model")!!

// Create blank
val vmiBlank = vm.createBlankInstance()

// Create default
val vmiDefault = vm.createDefaultInstance()

// Create by index
for (i in 0 until vm.instanceCount) {
    val vmiIndexed = vm.createInstanceFromIndex(i)
}

// Create by name
val vmiNamed = vm.createInstanceFromName("My Instance")

final vm = file.viewModelByName("My View Model")!;

// Create blank
final vmiBlank = vm.createInstance();

// Create default
final vmiDefault = vm.createDefaultInstance();

// Create by index
for (int i = 0; i < vm.instanceCount; i++) {
final vmiIndexed = vm.createInstanceByIndex(i);
}

// Create by name
final vmiNamed = vm.createInstanceByName("My Instance");

// Dispose the view model instance
viewModelInstance.dispose();        

These APIs are only needed when the Data Binding Mode on the RiveWidget is set to Manual.

Otherwise, you can configure view model binding directly in the Unity Inspector under the Data section.

private void OnEnable()
{
    riveWidget.OnWidgetStatusChanged += HandleWidgetStatusChanged;
}

private void OnDisable()
{
    riveWidget.OnWidgetStatusChanged -= HandleWidgetStatusChanged;
}

private void HandleWidgetStatusChanged()
{
    if (riveWidget.Status == WidgetStatus.Loaded)
    {
        // From a ViewModel reference
        ViewModel vm = riveWidget.File.GetViewModelByName("My View Model");
        
        // Create blank
        ViewModelInstance vmiBlank = vm.CreateInstance();
        
        // Create default
        ViewModelInstance vmiDefault = vm.CreateDefaultInstance();
        
        // Create by index
        for (int i = 0; i < vm.InstanceCount; i++)
        {
            ViewModelInstance vmiIndexed = vm.CreateInstanceAt(i);
        }
        
        // Create by name
        ViewModelInstance vmiNamed = vm.CreateInstanceByName("My Instance");
    }
}

The created instance can then be assigned to a state machine or artboard. This establishes the bindings set up at edit time.

It is preferred to assign to a state machine, as this will automatically apply the instance to the artboard as well. Only assign to an artboard if you are not using a state machine, i.e. your file is static or uses linear animations.

The initial values of the instance are not applied to their bound elements until the state machine or artboard advances.

const rive = new rive.Rive({
    autoBind: false, // This should be set to false (default)
    onLoad: () => {
        const vm = rive.viewModelByName("My View Model");
        const vmi = vm.instanceByName("My Instance");

        // Manually bind by applying the instance to the state machine and artboard
        rive.bindViewModelInstance(vmi);
    }        
});

const rive = new rive.Rive({
    autoBind: false, // This should be set to false (default)
    onLoad: () => {
        const vm = rive.viewModelByName("My View Model");
        const vmi = vm.instanceByName("My Instance");

        // Manually bind by applying the instance to the state machine and artboard
        rive.bindViewModelInstance(vmi);
    }        
});

let riveViewModel = RiveViewModel(...)
let artboard = riveViewModel.riveModel!.artboard,
let instance = riveViewModel.riveModel!.riveFile.defaultViewModel(for: artboard).createDefaultInstance()!

// Apply the instance to the state machine (preferred)
// Applying to a state machine will automatically bind to its artboard
riveViewModel.riveModel!.stateMachine.bind(instance) 
    
// Alternatively, apply the instance to the artboard
artboard.bind(viewModelInstance: instance)

view.setRiveResource(
    R.raw.my_rive_file,
    artboardName = "My Artboard",
)

val vm = view.controller.file?.getViewModelByName("My View Model")!!
val vmi = vm.createInstanceFromName("My Instance")

// Apply the instance to the state machine (preferred)
view.controller.stateMachines.first().viewModelInstance = vmi

// Alternatively, apply the instance to the artboard
view.controller.activeArtboard?.viewModelInstance = vmi

final file = await File.asset(
'assets/my_file.riv',
riveFactory: Factory.rive,
);

final artboard = file!.defaultArtboard();
final stateMachine = artboard!.defaultStateMachine()!;

final vm = file.defaultArtboardViewModel(artboard)!;
final vmi = vm.createDefaultInstance()!;

// Bind to the state machine. This automatically binds to the artboard as well.
stateMachine.bindViewModelInstance(vmi);

// If you're not using a state machine, bind to the artboard
artboard.bindViewModelInstance(vmi);        

// Access the RiveWidget component

// Using the Unity Inspector
// 1. Select your RiveWidget in the Inspector
// 2. In the "Data" section, set the Data Binding Mode:
//    - Auto Bind Default: Automatically binds the default view model instance
//    - Auto Bind Selected: Uses a specific instance you select in the dropdown
//    - Manual: Requires you to manually set up binding in code

// Or programmatically if set to Manual or if using the low-level API
private void OnEnable()
{
    riveWidget.OnWidgetStatusChanged += HandleWidgetStatusChanged;
}

private void OnDisable()
{
    riveWidget.OnWidgetStatusChanged -= HandleWidgetStatusChanged;
}

private void HandleWidgetStatusChanged()
{
    if (riveWidget.Status == WidgetStatus.Loaded)
    {
        ViewModel vm = riveWidget.Artboard.ViewModel;
        ViewModelInstance vmi = vm.CreateDefaultInstance();
        
        // Applying to a state machine will automatically bind to its artboard
        riveWidget.StateMachine.BindViewModelInstance(vmi);
    }
}

Auto-Binding

Alternatively, you may prefer to use auto-binding. This will automatically bind the default view model of the artboard using the default instance to both the state machine and the artboard. The default view model is the one selected on the artboard in the editor dropdown. The default instance is the one marked “Default” in the editor.

const rive = new rive.Rive({
    src: "my_rive_file.riv",
    canvas: document.getElementById("canvas"),
    autoBind: true,
    onLoad: () => {
        // Access the current instance that was auto-bound
        let boundInstance = rive.viewModelInstance;
    }
});

const rive = new rive.Rive({
    src: "my_rive_file.riv",
    canvas: document.getElementById("canvas"),
    autoBind: true,
    onLoad: () => {
        // Access the current instance that was auto-bound
        let boundInstance = rive.viewModelInstance;
    }
});

let riveViewModel = RiveViewModel(...)
riveViewModel.riveModel.enableAutoBind { instance in
    // Store a reference to `instance` to later access properties
    // The instance may change as state machines and artboards change
}

// If you'd like to disable autoBind after enabling…
riveViewModel.riveModel!.disableAutoBind()

view.setRiveResource(
    R.raw.my_rive_file,
    autoBind = true,
)

Flutter (rive_native) does not support auto-binding at this time. Higher level widgets will expose this functionality in the future.

See the RivePlayer.dart file in the example app for a demo of how this will be presented.

Rive Widget provides both visual and programmatic ways to configure auto-binding. In the Inspector, you can easily set up binding through the Data Binding Mode dropdown:

To enable auto-binding programmatically, use the following APIs:

// Before the widget is loaded:

// Option 1: Auto bind the default instance
riveWidget.BindingMode = DataBindingMode.AutoBindDefault;

// Option 2: Auto bind a specific instance by name
riveWidget.BindingMode = DataBindingMode.AutoBindSelected;
riveWidget.ViewModelInstanceName = "My Instance";

// Load the Rive file after setting the binding mode
riveWidget.Load(riveFile, artboardName, stateMachineName);

...
// Access the current instance that was auto-bound
ViewModelInstance boundInstance = riveWidget.StateMachine.ViewModelInstance;

Properties

A property is a value that can be read, set, or observed on a view model instance. Properties can be of the following types:

Type	Supported
Floating point numbers	✅
Booleans	✅
Triggers	✅
Strings	✅
Enumerations	✅
Colors	✅
Nesting	✅
Lists	🚧 Coming soon
Images	🚧 Coming soon

Property descriptors can be inspected on a view model to discover at runtime which are available. These are not the mutable properties themselves though - once again those are on instances. These descriptors have a type and name.

// A list of properties on a view model (ViewModel)
const properties = viewModel.properties;
console.log(properties);

// A list of properties on a view model (ViewModel)
const properties = viewModel.properties;
console.log(properties);

let riveViewModel = RiveViewModel(...)
let viewModel = riveViewModel.riveModel!.file.viewModelNamed(...)!
for property in viewModel.properties {
    print(property.type) // String, number, boolean, etc
    print(property.name) // The name of the property within the view model
}

val vm = view.controller.file?.getViewModelByName("My View Model")!!

// A list of properties
val properties = vm.properties
assertContains(
    properties,
    ViewModel.Property(ViewModel.PropertyDataType.NUMBER, "My Number Property")
)

// Accesss on a ViewModel object
print("Properties: ${viewModel.properties}");

// Access on a ViewModelInstance object
print("Properties: ${viewModelInstance.properties}");

var vm = riveWidget.File.GetViewModelByName("My View Model");

// A list of properties
var properties = vm.Properties;
foreach (var prop in properties)
{
    Debug.Log($"Property: {prop.Name}, Type: {prop.Type}");
}

Mutable Properties

View model instances have mutable properties. References to these properties can be retrieved by name. They have get, set, and observe operations. Getting or observing the value will retrieve the latest value set on that properties binding, as of the last state machine or artboard advance. Setting the value will update the value and all of its bound elements.

Trigger properties do not have a get operation - only set and observe.

After setting a property’s value, the changes will not apply to their bound elements until the state machine or artboard advances.

const rive = new rive.Rive({
    autoBind: true,
    onLoad: () => {
        // Access the current instance that was auto-bound
        let vmi = rive.viewModelInstance;
        const numberProperty = vmi.number("My Number Property");
        // Get
        const numberValue = numberProperty.value();
        // Set
        numberProperty.value(10);
    }             
});

const rive = new rive.Rive({
    autoBind: true,
    onLoad: () => {
        // Access the current instance that was auto-bound
        let vmi = rive.viewModelInstance;
        const numberProperty = vmi.number("My Number Property");
        // Get
        const numberValue = numberProperty.value();
        // Set
        numberProperty.value(10);
    }             
});

let riveViewModel = RiveViewModel(...)
let instance = riveViewModel.riveModel!.riveFile.viewModelNamed("...")!.createDefaultInstance()!

// Strings
let stringProperty = instance.stringProperty(fromPath: "...")!
// Updating its value
stringProperty.value = "Hello, Rive"
// Get its value
print(stringProperty.value)

// You can also set and get values without storing a strong reference
instance.stringProperty(fromPath: "...").value = "Hello again, Rive"

// Numbers
let numberProperty = instance.numberProperty(fromPath: "...")!
// Updating its value
numberProperty.value = 1337
// Get its value
print(numberProperty.value)

// You can also set and get values without storing a strong reference
instance.numberProperty(fromPath: "...").value = 1337

// Booleans
let booleanProperty = instance.booleanProperty(fromPath: "...")!
// Updating its value
booleanProperty.value = true
// Get its value
print(booleanProperty.value)

// You can also set and get values without storing a strong reference
instance.booleanProperty(fromPath: "...").value = true

// Colors
let colorProperty = instance.colorProperty(fromPath: "...")!
// Updating its value, which is a UIColor/NSColor, so all static helpers apply.
colorProperty.value = .red
// Get its value
print(colorProperty.value)

// You can also set and get values without storing a strong reference
instance.colorProperty(fromPath: "...").value = .red

// Enums
let enumProperty = instance.enumProperty(fromPath: "...")!
// Updating its value
enumProperty.value = "Foo"
// Get its value
print(enumProperty.value)
// Print all possible values
print(enumProperty.values)

// You can also set and get values without storing a strong reference
instance.enumProperty(fromPath: "...").value = "Foo"

// Trigger
let triggerProperty = instance.triggerProperty(fromPath: "...")!
// Fire the trigger
triggerProperty.trigger()

val vm = view.controller.file?.getViewModelByName("My View Model")!!
val vmi = vm.createInstanceFromName("My Instance")

val numberProperty = vmi.getNumberProperty("My Number Property")
// Get
val numberValue = numberProperty.value
// Set
numberProperty.value = 10f

final vm = file.defaultArtboardViewModel(artboard)!;
final vmi = vm.createDefaultInstance()!;

final numberProperty = vmi.number("My Number Property")!;
// Get
final numberValue = numberProperty.value;

// Set
numberProperty.value = 10;

// Observe
void onNumberChange(double value) {
    print("Number changed to: $value");
}
numberProperty.addListener(onNumberChange);

// Remove listener when done
numberProperty.removeListener(onNumberChange);

// Alternatively, clear all listeners
numberProperty.clearListeners();

// Dispose of the property to clear up resources when you're no longer using it
// This will call `clearListeners()` internally.
numberProperty.dispose();        

private void OnEnable()
{
    riveWidget.OnWidgetStatusChanged += HandleWidgetStatusChanged;
}

private void OnDisable()
{
    riveWidget.OnWidgetStatusChanged -= HandleWidgetStatusChanged;
}

private void HandleWidgetStatusChanged()
{
    // Check if the widget is loaded before accessing the view model instance
    if (riveWidget.Status == WidgetStatus.Loaded)
    {
        ViewModelInstance viewModelInstance = riveWidget.StateMachine.ViewModelInstance;
        
     //==========================================================================
    // STRING PROPERTIES
    //==========================================================================
        ViewModelInstanceStringProperty stringProperty = viewModelInstance.GetStringProperty("title");
        Debug.Log($"String value: {stringProperty.Value}");
        stringProperty.Value = "New Text";
        
    //==========================================================================
    // NUMBER PROPERTIES
    //==========================================================================
        ViewModelInstanceNumberProperty numberProperty = viewModelInstance.GetNumberProperty("count");
        Debug.Log($"Number value: {numberProperty.Value}");
        numberProperty.Value = 42.5f;
        
    //==========================================================================
    // BOOLEAN PROPERTIES
    //==========================================================================
        ViewModelInstanceBooleanProperty boolProperty = viewModelInstance.GetBooleanProperty("isActive");
        Debug.Log($"Boolean value: {boolProperty.Value}");
        boolProperty.Value = true;
        
    //==========================================================================
    // COLOR PROPERTIES
    //==========================================================================
        ViewModelInstanceColorProperty colorProperty = viewModelInstance.GetColorProperty("backgroundColor");
        // Using Unity Color (float values 0-1)
        Color currentColor = colorProperty.Value;
        colorProperty.Value = new UnityEngine.Color(1, 0, 0, 1); // Red color
        // Or using Color32 (byte values 0-255)
        Color32 currentColor32 = colorProperty.Value32;
        colorProperty.Value32 = new Color32(0, 255, 0, 255); // Green color
        
    //==========================================================================
    // ENUM PROPERTIES
    //==========================================================================
        ViewModelInstanceEnumProperty enumProperty = viewModelInstance.GetEnumProperty("category");
        Debug.Log($"Enum current value: {enumProperty.Value}");
        Debug.Log($"Enum available values: {string.Join(", ", enumProperty.EnumValues)}");
        enumProperty.Value = "option_name";
        
    //==========================================================================
    // TRIGGER PROPERTIES
    //==========================================================================
        ViewModelInstanceTriggerProperty triggerProperty = viewModelInstance.GetTriggerProperty("onSubmit");
        triggerProperty.Trigger(); // Fire the trigger
    }
}

Observability

You can observe changes over time to property values, either by using listeners or a platform equivalent method. Once observed, you will be notified when the property changes are applied by a state machine advance, whether that is a new value that has been explicitly set or if the value was updated as a result of a binding. Observing trigger properties is an alternative method to receive events from the editor, as compared to Rive Events.

Adding an observer to a property is done by calling the on method on the property.

public on(callback: EventCallback)

The observer can be removed by calling the off method on the property and passing the callback function. Alternatively, you can call off() without any arguments to remove all observers.

public off(callback?: EventCallback)

Example:

const rive = new rive.Rive({
    autoBind: true,
    onLoad: () => {
        // Access the current instance that was auto-bound
        let vmi = rive.viewModelInstance;
        const numberProperty = vmi.number("My Number Property");
        // Observe
        numberProperty.on((event) => {
            console.log(event.data);
        });
        // Remove all listener when done
        numberProperty.off();
    }             
});

Adding an observer to a property is done by calling the on method on the property.

public on(callback: EventCallback)

The observer can be removed by calling the off method on the property and passing the callback function. Alternatively, you can call off() without any arguments to remove all observers.

public off(callback?: EventCallback)

Example:

const rive = new rive.Rive({
    autoBind: true,
    onLoad: () => {
        // Access the current instance that was auto-bound
        let vmi = rive.viewModelInstance;
        const numberProperty = vmi.number("My Number Property");
        // Observe
        numberProperty.on((event) => {
            console.log(event.data);
        });
        // Remove all listener when done
        numberProperty.off();
    }             
});

let riveViewModel = RiveViewModel(...)
let instance = riveViewModel.riveModel!.riveFile.viewModelNamed("...")!.createDefaultInstance()!

// Get the string property
let stringProperty = instance.stringProperty(fromPath: "...")!

// Add a listener
let listener = stringProperty.addListener { newValue in
    print(newValue)
}

// Remove a listener, where listener is the return value of addListener
stringProperty.removeListener(listener)

// Trigger properties can also be listened to for when they are triggered
instance.triggerProperty(fromPath: "...")!.addListener { 
    print("Triggered!")
}

val vm = view.controller.file?.getViewModelByName("My View Model")!!
val vmi = vm.createInstanceFromName("My Instance")

val numberProperty = vmi.getNumberProperty("My Number Property")
// Observe
lifecycleScope.launch {
    numberProperty.collect { value ->
        Log.i("MyActivity", "Value: $value")
    }
}
// Or collect in Compose
val numberValue by numberProperty.collectAsState()

final vm = file.defaultArtboardViewModel(artboard)!;
final vmi = vm.createDefaultInstance()!;

final numberProperty = vmi.number("My Number Property")!;
// Get
final numberValue = numberProperty.value;

// Set
numberProperty.value = 10;

// Observe
void onNumberChange(double value) {
    print("Number changed to: $value");
}
numberProperty.addListener(onNumberChange);

// Remove listener when done
numberProperty.removeListener(onNumberChange);

// Alternatively, clear all listeners
numberProperty.clearListeners();

// Dispose of the property to clear up resources when you're no longer using it
// This will call `clearListeners()` internally.
numberProperty.dispose();        

private ViewModelInstanceNumberProperty numberProperty;
private ViewModelInstanceStringProperty stringProperty;
private ViewModelInstanceBooleanProperty boolProperty;
private ViewModelInstanceColorProperty colorProperty;
private ViewModelInstanceEnumProperty enumProperty;
private ViewModelInstanceTriggerProperty triggerProperty;

private void OnEnable()
{
    riveWidget.OnWidgetStatusChanged += HandleWidgetStatusChanged;
}

private void OnDisable()
{
    riveWidget.OnWidgetStatusChanged -= HandleWidgetStatusChanged;
}

private void HandleWidgetStatusChanged()
{
    if (riveWidget.Status == WidgetStatus.Loaded)
    {
        ViewModelInstance viewModelInstance = riveWidget.StateMachine.ViewModelInstance;
        
        // Add listeners to properties
        numberProperty = viewModelInstance.GetNumberProperty("count");
        numberProperty.OnValueChanged += OnNumberPropertyChanged;
        
        stringProperty = viewModelInstance.GetStringProperty("title");
        stringProperty.OnValueChanged += OnStringPropertyChanged;
        
        boolProperty = viewModelInstance.GetBooleanProperty("isActive");
        boolProperty.OnValueChanged += OnBoolPropertyChanged;
        
        colorProperty = viewModelInstance.GetColorProperty("backgroundColor");
        colorProperty.OnValueChanged += OnColorPropertyChanged;
        
        enumProperty = viewModelInstance.GetEnumProperty("category");
        enumProperty.OnValueChanged += OnEnumPropertyChanged;
        
        triggerProperty = viewModelInstance.GetTriggerProperty("onSubmit");
        triggerProperty.OnValueChanged += OnTriggerPropertyFired;
        
     
    }
}

private void OnNumberPropertyChanged()
{
    Debug.Log($"Number changed to: {numberProperty.Value}");
}

private void OnStringPropertyChanged()
{
    Debug.Log($"String changed to: {stringProperty.Value}");
}

private void OnBoolPropertyChanged()
{
    Debug.Log($"Boolean changed to: {boolProperty.Value}");
}

private void OnColorPropertyChanged()
{
    Debug.Log($"Color changed to: {ColorUtility.ToHtmlStringRGBA(colorProperty.Value)}");
}

private void OnEnumPropertyChanged()
{
    Debug.Log($"Enum changed to: {enumProperty.Value}");
}

private void OnTriggerPropertyFired()
{
    Debug.Log("Trigger fired!");
}

private void OnDestroy()
{
    // You should remove listeners when no longer needed,
    numberProperty.OnValueChanged -= OnNumberPropertyChanged;
    stringProperty.OnValueChanged -= OnStringPropertyChanged;
    boolProperty.OnValueChanged -= OnBoolPropertyChanged;
    colorProperty.OnValueChanged -= OnColorPropertyChanged;
    enumProperty.OnValueChanged -= OnEnumPropertyChanged;
    triggerProperty.OnValueChanged -= OnTriggerPropertyFired;
}

Enums

Enums properties come in two flavors: system and user-defined. In practice, you will not need to worry about the distinction, but just be aware that system enums are available in any Rive file that binds to an editor-defined enum set, representing options from the editor’s dropdowns, where user-defined enums are those defined by a designer in the editor.

Enums are string typed. The Rive file contains a list of enums. Each enum in turn has a name and a list of strings.

const rive = new rive.Rive({
    onLoad: () => {
        const enums = rive.enums();

        console.log(enums);
    }           
});

const rive = new rive.Rive({
    onLoad: () => {
        const enums = rive.enums();

        console.log(enums);
    }           
});

val enums = view.controller.file?.enums!!

val firstEnumName = enums[0].name
val firstEnumFirstValue = enums[0].values[0]

// Accesss on a File object
print("Data enums: ${file.enums}");

    var viewModelInstance = riveWidget.StateMachine.ViewModelInstance;
    
    // Accessing enums from the file
    var enums = riveWidget.File.ViewModelEnums;
    foreach (var enumType in enums)
    {
        Debug.Log($"Enum: {enumType.Name}");
        foreach (var value in enumType.Values)
        {
            Debug.Log($" - Value: {value}");
        }
    }

    ...
    // Using enum properties
    var enumProperty = viewModelInstance.GetEnumProperty("category");
    Debug.Log($"Current value: {enumProperty.Value}");
    Debug.Log($"Available values: {string.Join(", ", enumProperty.EnumValues)}");
    enumProperty.Value = enumProperty.EnumValues[0]; // Set to first value

Nested Property Paths

View models can have properties of type view model, allowing for arbitrary nesting. We could chain property calls on each instance starting from the root until we get to the property of interest. Alternatively we can do this through a path parameter, which is similar to a URI in that it is a forward slash delimited list of property names ending in the name of the property of interest.

const rive = new rive.Rive({
    autoBind: true,
    onLoad: () => {
        // Access the current instance that was auto-bound
        let vmi = rive.viewModelInstance;

        const nestedNumberByChain = vmi
            .viewModel("My Nested View Model")
            .viewModel("My Second Nested VM")
            .number("My Nested Number");

        const nestedNumberByPath = vmi.number("My Nested View Model/My Second Nested VM/My Nested Number");
    }           
});

const rive = new rive.Rive({
    autoBind: true,
    onLoad: () => {
        // Access the current instance that was auto-bound
        let vmi = rive.viewModelInstance;

        const nestedNumberByChain = vmi
            .viewModel("My Nested View Model")
            .viewModel("My Second Nested VM")
            .number("My Nested Number");

        const nestedNumberByPath = vmi.number("My Nested View Model/My Second Nested VM/My Nested Number");
    }           
});

let riveViewModel = RiveViewModel(...)
let instance = riveViewModel.riveModel!.riveFile.viewModelNamed("...")!.createDefaultInstance()!

let nestedNumberByChain = instance
                            .viewModelInstanceProperty(fromPath: "Nested View Model")
                            .viewModelInstanceProperty(fromPath: "Another Nested View Model")
                            .numberProperty(fromPath: "Number")

let nestedNumberByPath = instance.numberProperty(fromPath: "Nested View Model/Another Nested View Model/Number")

val vm = view.controller.file?.getViewModelByName("My View Model")!!
val vmi = vm.createInstanceFromName("My Instance")

val nestedNumberByChain = vmi
    .getInstanceProperty("My Nested View Model")
    .getInstanceProperty("My Second Nested VM")
    .getNumberProperty("My Nested Number")

val nestedNumberByPath = vmi
    .getNumberProperty("My Nested View Model/My Second Nested VM/My Nested Number")

final vm = file.viewModelByName("My View Model")!;
final vmi = vm.createInstanceByName("My Instance")!;

final nestedNumberByChain = vmi
    .viewModel("My Nested View Model")!
    .viewModel("My Second Nested VM")!
    .number("My Nested Number");

final nestedNumberByPath = vmi.number("My Nested View Model/My Second Nested VM/My Nested Number");        

if (riveWidget.Status == WidgetStatus.Loaded)
{
    var viewModelInstance = riveWidget.StateMachine.ViewModelInstance;
    
    // Accessing nested view models using chaining
    var nestedNumberByChain = viewModelInstance
        .GetViewModelInstanceProperty("My Nested View Model")
        .GetViewModelInstanceProperty("My Second Nested VM")
        .GetNumberProperty("My Nested Number");
    
    // Accessing nested properties using path notation
    var nestedNumberByPath = viewModelInstance
        .GetNumberProperty("My Nested View Model/My Second Nested VM/My Nested Number");
    

}

Examples

See this video for an intro to data binding using the Web runtime along with this CodeSandbox example.

See the Data Binding view in the Example app for a demo.

See the examples/data_binding.dart file in the example app on Pub for a demo.

dart pub unpack rive_native # Unpack the package source code and example app
cd rive_native/example      # Navigate to the example folder
flutter create .            # Create the platform folders
flutter pub get             # Fetch dependencies
flutter run                 # Run the example app

Runtime Fundamentals

App Runtimes

Data Binding

Overview

Data Binding Concepts

View Models

View Model Instances

Auto-Binding

Properties

Mutable Properties

Observability

Enums

Nested Property Paths

Examples

Runtime Fundamentals

App Runtimes

​Overview

Data Binding Concepts

​View Models

​View Model Instances

​Auto-Binding

​Properties

​Mutable Properties

​Observability

​Enums

​Nested Property Paths

​Examples

Overview

View Models

View Model Instances

Auto-Binding

Properties

Mutable Properties

Observability

Enums

Nested Property Paths

Examples