Data Binding is in Early Access and is not yet available for production. Runtime support may be limited or unavailable. See Feature Support for updates.

As data binding continues to develop additional features, we suggest you continue to refer to this page for changes.

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.

Only the web runtime is released at this time. The Android APIs are provided as a preview.

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.

const rive = new rive.Rive({
    src: "my_rive_file.riv",
    canvas: document.getElementById("canvas"),
    onLoad: () => {
        // 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();
    }
});

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:

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

    TypeValue
    Number0
    StringEmpty string
    BooleanFalse
    Color#000000FF
    TriggerUntriggered
    EnumThe first value
    Nested view modelNull
  2. 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.

  3. Create by index - Using the order returned when iterating over all available instances. Useful when creating multiple instances by iteration.

  4. Create by name - Use the editor’s instance name. Useful when creating a specific instance.

const rive = new rive.Rive({
    onLoad: () => {
        const vm = rive.viewModelByName("My View Model");

        // Create blank
        const vmiBlank = vm.instance();

        // Create default
        const vmiDefault = vm.defaultInstance();

        // Create by index
        for (let i = 0; i < vm.instanceCount; i++) {
            const vmiIndexed = vm.instanceByIndex(i);
        }

        // Create by name
        const vmiNamed = vmvm.instanceByName("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({
    onLoad: () => {
        const vm = rive.viewModelByName("My View Model");
        const vmi = vm.instanceByName("My Instance");

        // Apply the instance to the state machine and artboard
        rive.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,
});

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:

TypeSupported
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.

const rive = new rive.Rive({
    onLoad: () => {
        const vm = rive.viewModelByName("My View Model");
        const vmi = vm.instanceByName("My Instance");

        // A list of properties
        const properties = vm.properties;
        console.log(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({
    onLoad: () => {
        const vm = rive.viewModelByName("My View Model");
        const vmi = vm.instanceByName("My Instance");

        const numberProperty = vmi.number("My Number Property");
        // Get
        const numberValue = numberProperty.value();
        // Set
        numberProperty.value(10);
        // Observe
        numberProperty.on((event) => {
            console.log(event.data);
        });
    }             
});

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);
    }           
});

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({
    onLoad: () => {
        const vm = rive.viewModelByName("My View Model");
        const vmi = vm.instanceByName("My Instance");

        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");
    }           
});