Data Binding with ViewModels

Data Binding is an advanced feature in Rive that allows you to connect your application's state directly to properties within your Rive animation. This is managed through a ViewModel, which you create in the Rive editor.

This approach powerfully decouples your animation logic from your application logic, making both easier to author and maintain.

Note: Data Binding is only available with the @rive-app/react-webgl2 package.

Why Use Data Binding?

While useStateMachineInput is great for direct control, Data Binding offers several advantages:

  • Decoupling: Your React code doesn't need to know the specific names of state machine inputs. It only needs to know the property names defined in the ViewModel (e.g., "username", "isLoading"). Animators can change the underlying state machine without requiring code changes in the app, as long as the ViewModel contract is maintained.
  • Centralized Logic: All animation-related properties are defined in one place in the Rive editor, creating a clear API for your animation.
  • Type Safety and Richer APIs: The useViewModel hooks provide typed values and specialized functions for different property types (e.g., setRgb for colors, addInstance for lists).
  • Instance Management: Easily work with multiple, distinct instances of a ViewModel, each with its own state.

The Core Concepts

  1. ViewModel: A contract defined in the Rive editor. It exposes a set of properties (strings, numbers, booleans, triggers, etc.) that can be linked to elements within your animation.
  2. ViewModelInstance: A live instance of a ViewModel in the runtime. Your React application interacts with these instances to get and set property values.
  3. Data Binding Hooks: A family of hooks (useViewModel, useViewModelInstance, useViewModelInstanceString, etc.) that provide the bridge between your React components and the ViewModelInstances.

Ready to get started? Head to the Setup Guide to learn how to initialize data binding in your component.