Skip to content

v0.4.0 — Data Binding & ViewModel Support

Choose a tag to compare

View all tags
@andrei-shpileuski andrei-shpileuski released this 23 Feb 13:17
· 7 commits to main since this release
v0.4.0
306bc61

@grandgular/rive-angular v0.4.0

Major feature release adding full Rive Data Binding and ViewModel support with declarative and imperative APIs. Brings Angular library to feature parity with React's @rive-app/react-webgl2 hooks.

🎉 What's New

Declarative Data Binding

🔗 dataBindings Input — New reactive input for template-driven ViewModel property updates. Keys present in the input are controlled — the input is the source of truth.

<rive-canvas
  src="assets/game.riv"
  [dataBindings]="{
    backgroundColor: '#FF5733',
    score: playerScore(),
    playerName: userName(),
    isActive: true
  }"
/>

ViewModel Selection

🎯 viewModelName Input — Select which ViewModel to use (defaults to artboard's default ViewModel). Changing this input after load automatically reinitializes the ViewModel.

<rive-canvas
  src="assets/multi-vm.riv"
  viewModelName="GameViewModel"
/>

Two-Way Reactivity

↔️ dataBindingChange Output — React to property changes from within the animation, including trigger events.

onDataChange(event: DataBindingChangeEvent) {
  console.log(`${event.path} changed to ${event.value}`);
  // event.propertyType: 'color' | 'number' | 'string' | 'boolean' | 'enum' | 'trigger'
}
<rive-canvas
  src="assets/interactive.riv"
  (dataBindingChange)="onDataChange($event)"
/>

Universal Data Binding Methods

🔧 Auto-Detecting API — Set and get any ViewModel property with automatic type detection.

riveRef = viewChild.required(RiveCanvasComponent);

// Auto-detects property types
this.riveRef().setDataBinding('score', 100);        // number
this.riveRef().setDataBinding('playerName', 'Bob'); // string
this.riveRef().setDataBinding('isActive', true);    // boolean

const score = this.riveRef().getDataBinding('score'); // returns number

// Fire triggers
this.riveRef().fireViewModelTrigger('onComplete');

Color Manipulation (Resolves ng-rive #56)

🎨 Rich Color API — Set and manipulate colors using multiple formats: hex strings, ARGB integers, or RiveColor objects.

// Multiple color formats supported
this.riveRef().setColor('backgroundColor', '#FF5733');           // hex string
this.riveRef().setColor('backgroundColor', 0xFFFF5733);          // ARGB integer
this.riveRef().setColor('backgroundColor', { r: 255, g: 87, b: 51, a: 255 });

// RGBA components
this.riveRef().setColorRgba('backgroundColor', 255, 87, 51, 255);

// Opacity manipulation (preserves RGB)
this.riveRef().setColorOpacity('backgroundColor', 0.5); // 0.0-1.0

// Get color
const color = this.riveRef().getColor('backgroundColor');
// Returns: { r: 255, g: 87, b: 51, a: 255 }

Color Utilities (Exported)

🛠️ Standalone Color Tools — Utility functions exported for consumer use.

import { parseRiveColor, riveColorToArgb, riveColorToHex } from '@grandgular/rive-angular';

// Parse any color format
const color = parseRiveColor('#FF5733');
// Returns: { r: 255, g: 87, b: 51, a: 255 }

// Convert to formats
const argb = riveColorToArgb(color);  // 0xFFFF5733
const hex = riveColorToHex(color);    // '#FF5733FF'

Controlled vs Uncontrolled Semantics

⚖️ React-inspired pattern — Keys in dataBindings input are controlled (input wins on every update). Keys outside are uncontrolled (managed imperatively). Calling setDataBinding() on a controlled key logs a warning in debug mode.

Advanced ViewModel Access

🔬 viewModelInstance Signal — Direct access to the ViewModel instance for advanced scenarios.

const vm = this.riveRef().viewModelInstance();
if (vm) {
  console.log('ViewModel properties:', vm.properties);
}

Error Handling

🏷️ New RIVE_4xx Error Codes — Data Binding validation errors emitted through loadError output:

Code Name Description
RIVE_401 ViewModelNotFound Specified ViewModel not found in file
RIVE_402 DataBindingPropertyNotFound Property path not found in ViewModel
RIVE_403 DataBindingTypeMismatch Value type mismatch, invalid color format, or opacity out of range

📐 API Reference

New Component Inputs

Input Type Description
dataBindings Record<string, DataBindingValue> Declarative ViewModel property bindings (controlled keys)
viewModelName string | undefined ViewModel name to use (defaults to artboard's default)

New Component Outputs

Output Type Description
dataBindingChange EventEmitter<DataBindingChangeEvent> Emits when ViewModel properties change from animation

New Component Signals

Signal Type Description
viewModelInstance Signal<ViewModel | null> Direct access to current ViewModel instance

New Component Methods

Method Signature Description
setDataBinding (path: string, value: DataBindingValue): void Set any ViewModel property (auto-detects type)
getDataBinding (path: string): DataBindingValue | undefined Get any ViewModel property (auto-detects type)
fireViewModelTrigger (path: string): void Fire a trigger property
setColor (path: string, color: string | number | RiveColor): void Set color (hex, ARGB, or object)
getColor (path: string): RiveColor | undefined Get color as RiveColor object
setColorRgba (path: string, r: number, g: number, b: number, a?: number): void Set color using RGBA components
setColorOpacity (path: string, opacity: number): void Set opacity (0.0-1.0)

New Exported Types

interface RiveColor {
  r: number;  // 0-255
  g: number;  // 0-255
  b: number;  // 0-255
  a: number;  // 0-255
}

type DataBindingValue = number | string | boolean | RiveColor;

type DataBindingPropertyType = 
  | 'number' 
  | 'string' 
  | 'boolean' 
  | 'color' 
  | 'enum' 
  | 'trigger';

interface DataBindingChangeEvent {
  path: string;
  value: DataBindingValue;
  propertyType: DataBindingPropertyType;
}

New Exported Utilities

// Color parsing and conversion
function parseRiveColor(input: string | number | RiveColor): RiveColor;
function riveColorToArgb(color: RiveColor): number;
function riveColorToHex(color: RiveColor): string;

🔄 Architecture

Data Binding uses Rive's official ViewModel system (introduced in @rive-app/canvas ^2.35.0) instead of direct shape manipulation. ViewModels are created in the Rive editor and provide:

  • Type-safe property bindings
  • Designer-friendly workflow
  • Two-way reactivity
  • Automatic UI updates

✅ No Breaking Changes

  • All new features are optional and additive
  • dataBindings input is optional — existing templates unaffected
  • All new methods are purely additive
  • No existing API signatures changed
  • Files without ViewModels work exactly as before

📚 Documentation

  • Updated README with Data Binding examples (declarative, imperative, color manipulation)
  • Updated error codes table with RIVE_401, RIVE_402, RIVE_403
  • Updated API reference with 8 new methods and 3 new inputs/outputs
  • Added Color Utilities section
  • See CHANGELOG.md for complete details

🎯 Issue Resolution

This release resolves ng-rive issue #56 — "How to set solid color dynamically?" by providing a comprehensive color manipulation API through the ViewModel system.

🙏 Thanks

All 112 tests passing (53 new tests for Data Binding and color scenarios). Production-ready and feature-complete for dynamic data-driven animations.

Assets 3
Loading