Data Binding - UpstandPlatform/OpenRive GitHub Wiki

Data binding properties are how a Rive file and your app talk to each other: the file exposes named properties, transitions and listeners read and write them, and your code sets them at runtime.

They replace state machine inputs, which Rive deprecated. Files with inputs still play — Rive kept them working — but runtimes log a deprecation warning the moment your code touches the inputs API:

[Rive: state-machine-inputs] State machine inputs are deprecated and will be removed in a future major
version: please use data binding properties instead.

Properties do everything inputs did, plus strings and colors, and no runtime warns about them.

The Data tab sits beside Listeners under the state machine graph (Animate mode).

• Add property → number, boolean, trigger, string or color. The value you set there is the value the file starts with.
• Edit the view model name above the property list to identify the data contract for this artboard.
• Right-click a property to rename or delete it. Deleting also removes the conditions and listener actions that used it, so the file stays valid.
• Preview (Ctrl P) lists the properties of the running file and lets you change them live, which is the quickest way to check a transition.

When editing a transition, choose a data property to add a typed condition. Listener actions can set a property, align a node to the pointer, or fire a named event. The same property list appears in both places, so renaming or removing a property stays consistent with the conditions and actions that use it.

Use Convert inputs to data binding — in the Data tab when a file still has inputs, from the canvas right-click menu, or from the command list. It does what Rive's own "Convert Inputs to View Models" does:

1. creates a property for every input, with the same name, type and starting value,
2. rewrites every transition condition to read the property,
3. rewrites every listener action to set it,
4. removes the inputs.

Anything it cannot express with data binding keeps its input, and the editor says which and why:

Converting changes the runtime contract: code that called stateMachineInputs must move to viewModelInstance (the Code panel regenerates the snippet for you).

With autoBind: true the runtime binds the file's default instance, and properties are read and written through it:

import { Rive } from '@rive-app/canvas';

const rive = new Rive({
  src: '/button.riv',
  canvas: document.getElementById('canvas'),
  stateMachines: 'Button',
  autoplay: true,
  autoBind: true,
});

rive.on('load', () => {
  const vm = rive.viewModelInstance;
  vm.boolean('isHover').value = true;
  vm.number('level').value = 3;
  vm.string('label').value = 'Buy now';
  vm.color('tint').value = 0xff3d8bd0;
  vm.trigger('press').trigger();

  vm.boolean('isHover').on((value) => console.log('isHover is now', value));
});

React uses hooks over the same instance (useViewModelInstanceBoolean, …Number, …String, …Color, …Trigger). The Code panel's Embed tab writes the snippet for the file you have open, and preview bundles ship a player that already drives the properties.

For other runtimes, see Rive's data binding docs.

The same operations are available to scripts, the CLI and AI assistants:

get_project lists each artboard's properties, so an assistant can see what a file exposes before editing it. Lower level helpers (addProperty, propertyCondition, propertyListenerAction, removeProperty) live in packages/rive/src/databind.ts.

• binding a property to a shape's own properties (a color property driving a fill, a string driving a text run) — OpenRive reads and preserves these bindings in files that have them, but cannot create them,
• enum and list properties, nested view models, and data converters,
• blend states driven by properties.

Files that use those features import, edit and export byte for byte as usual; they simply cannot be created from the editor yet. Theme colors are a separate, editor-only feature — see theme colors.

_{This page is generated from docs/data-binding.md. Suggest an edit.}