- Bind the color of an icon to a color data property that can be adjusted by a developer at runtime
- Bind the X-position of an animated object so that it can be followed with an offset by another object
- Listen for a click event on two buttons to increment and decrement a counter
Why Use Data Binding?
Data binding decouples design and code by introducing intermediate data that both sides can bind to. This forms the “contract” between designers and developers. Once this contract is in place, both sides can iterate independently, speeding your ability to deliver new features and experiment with what’s possible. Within the editor, data binding allows for more reactivity in your designs. You can establish relationships between objects and ensure that certain invariants hold true, no matter the state of the artboard. The data binding system will ensure that these relationships are always up to date as animations and calls from code change the values. It also offers the opportunity to shift more logic into the Rive file and out of code. You will need to decide whether a piece of logic lives in code or data binding for your given use case, but one consideration is that any data binding logic will be universal across runtimes, rather than needing separate re-implementations.Glossary
Data binding introduces a number of concepts that you will need to familiarize yourself with. The names of these concepts are loosely derived from the Model, View, Viewmodel (MVVM) pattern in software development.Editor Element
For the purposes of data binding, an “editor element” simply refers to an editable UI element in the editor with a value that can have a binding attached to it.View Model
A view model is a blueprint for a collection of data. Developers might think of this as similar to a class in object-oriented programming. View models typically describe all of the associated data with a given use case - commonly one per artboard. View models themselves don’t have concrete values. For that, you must have an instance.View Model Property
A view model property is one piece of data within a view model. Developers might think of this as similar to a field in object-oriented programming. Properties have a data type which is selected when they are created and a name which can be referenced in code. Each property can be bound to different editor elements of the same type.Adding View Model properties
In the Data panel, click the Add View Model Property button next to the view model name and select your property type.
View Model Instance
A view model instance is the living version of a view model with actual values. Developers might think of this as similar to a class instance in object-oriented programming. Instances have the same properties as the view model they are derived from, except now each of these properties has a living value that can change over time. You may create as many instances as you’d like from a given view model. Each can be given a unique name associated with what those values represent. Each can have different initial values for its properties, representing a design-time configuration. For example, if you had a menu with three buttons with icons: 🏠 Home, 👤 Profile, and ❓ About, you might have a single artboard representing the menu item, but three view model instances, each with the menu item’s label and associated icon, that can be applied to that artboard to configure the buttons. Artboards are assigned an instance to populate the data bindings. Changing which instance is applied will change the initial state of the properties and all associated bound elements. In order for an instance to be visible to developers, it must be marked as Exported. Otherwise, it is considered internal to the file. One reason you may want to keep it internal is if you only use the instance to test your design when it is configured with a given set of values, including edge cases. These exported instances can then be assigned to an artboard at runtime by developers. Alternatively, developers can create empty instances which have default values, such as zero for numbers and empty strings. Once the instance is assigned, its values will begin updating according to the bindings.Binding
A binding is an association between a view model property and an editor element. For instance, you might have a string property called “name” bound to a text run. Once bound, the text run will take the value from the view model property. See Bind Direction for additional options.Absolute & Relative Binding
By default, new data binding connections are created as absolute binds.- Absolute Binding: the bind points the value at a specific property location within the view model tree. For example, “the second property of the first view model”.
- Relative Binding: the bind finds the value of property with a specific name, regardless of where it falls within the view model tree. For example, a relative binding to “myNumber” will look for a property of that name within the view model available.
Bind Direction
Bindings can be source to target, target to source, or bidirectional. In this case, “source” means the property, and “target” means the editor element. The default binding is source to target. This means that changes to the property update the value of the element. For example, an XPos property updates the X position of an object. Target to source means that changes to the element’s value update the property. For example, the X position of an object updates the XPos property. Bidirectional means that changes are applied in both directions, meaning either the element or the property can update the other. Additionally, a binding may be marked as “Bind Once”. This means that the initial value will apply and thereafter the binding will not apply any updates.View Model Nesting
View models can have another view model as one of their properties. This is referred to as “nesting”. This is useful when a parent instance wants to associate with a particular child instance, similar to components.Converter
A converter is a general purpose way of transforming a binding’s value when it is applied. These transformations might involve changing its type. For instance, the “Convert to String” converter can be used to convert a numerical binding to text, so that an object’s X position could be applied to a text run. To apply a converter on a value that already has a binding, right click on the bound property, click Update Bind, and select your converter from the Convert dropdown.Runtime APIs
To continue reading about how to interact with data binding in code, see the Runtime Overview page.Data Binding Runtime Overview
A dive into using data binding at runtime.