fix!: hooks start undefined, useViewModelInstance returns {instance, error}

useRiveNumber/String/Boolean/Color/Enum hooks start as undefined — the real
value arrives via listener. useViewModelInstance returns a discriminated union:
undefined (loading), null (resolved empty/error), or ViewModelInstance (success).

Author: mfazekas

example/__tests__/hooks.harness.tsx

@@ -26,14 +26,15 @@ type UseRiveNumberContext = {
   value: number | undefined;
   error: Error | null;
   setValue: ((v: number) => void) | null;
+  renderValues: (number | undefined)[];
 };
 
 function createUseRiveNumberContext(): UseRiveNumberContext {
-  return { value: undefined, error: null, setValue: null };
+  return { value: undefined, error: null, setValue: null, renderValues: [] };
 }
 
 type UseViewModelInstanceContext = {
-  instance: ViewModelInstance | null;
+  instance: ViewModelInstance | null | undefined;
   age: number | undefined;
 };
 
@@ -50,6 +51,8 @@ function UseRiveNumberTestComponent({
 }) {
   const { value, setValue, error } = useRiveNumber('health', instance);
 
+  context.renderValues.push(value);
+
   useEffect(() => {
     context.value = value;
     context.error = error;
@@ -70,7 +73,7 @@ function UseViewModelInstanceTestComponent({
   file: RiveFile;
   context: UseViewModelInstanceContext;
 }) {
-  const instance = useViewModelInstance(file);
+  const { instance } = useViewModelInstance(file);
 
   const age = useMemo(() => {
     if (!instance) return undefined;
@@ -96,6 +99,34 @@ function expectDefined<T>(value: T): asserts value is NonNullable<T> {
 }
 
 describe('useRiveNumber Hook', () => {
+  it('starts undefined then receives value via listener', async () => {
+    const file = await RiveFileFactory.fromSource(QUICK_START, undefined);
+    const vm = file.defaultArtboardViewModel();
+    expectDefined(vm);
+    const instance = vm.createDefaultInstance();
+    expectDefined(instance);
+
+    const context = createUseRiveNumberContext();
+
+    await render(
+      <UseRiveNumberTestComponent instance={instance} context={context} />
+    );
+
+    // First render must produce undefined — not a synchronous read from property.value
+    expect(context.renderValues[0]).toBeUndefined();
+
+    // After listener fires, value should be a number
+    await waitFor(
+      () => {
+        expect(context.error).toBeNull();
+        expect(typeof context.value).toBe('number');
+      },
+      { timeout: 5000 }
+    );
+
+    cleanup();
+  });
+
   it('returns value from number property', async () => {
     const file = await RiveFileFactory.fromSource(QUICK_START, undefined);
     const vm = file.defaultArtboardViewModel();

example/src/demos/DataBindingArtboardsExample.tsx

@@ -78,7 +78,12 @@ function ArtboardSwapper({
   mainFile: RiveFile;
   assetsFile: RiveFile;
 }) {
-  const instance = useViewModelInstance(mainFile);
+  const { instance, error } = useViewModelInstance(mainFile);
+
+  if (error) {
+    console.error(error.message);
+    return <Text style={{ color: 'red' }}>{error.message}</Text>;
+  }
   const [currentArtboard, setCurrentArtboard] = useState<string>('Dragon');
   const initializedRef = useRef(false);
 

example/src/demos/QuickStart.tsx

@@ -23,7 +23,7 @@ export default function QuickStart() {
     require('../../assets/rive/quick_start.riv')
   );
   const { riveViewRef, setHybridRef } = useRive();
-  const viewModelInstance = useViewModelInstance(riveFile, {
+  const { instance: viewModelInstance } = useViewModelInstance(riveFile, {
     onInit: (vmi) => vmi.numberProperty('health')!.set(9),
   });
 

example/src/exercisers/FontFallbackExample.tsx

@@ -258,7 +258,7 @@ function MountedView({ text }: { text: string }) {
     // https://rive.app/marketplace/26480-49641-simple-test-text-property/
     require('../../assets/rive/font_fallback.riv')
   );
-  const instance = useViewModelInstance(riveFile ?? null);
+  const { instance } = useViewModelInstance(riveFile ?? null);
 
   const { setValue: setRiveText, error: textError } = useRiveString(
     TEXT_PROPERTY,

example/src/exercisers/MenuListExample.tsx

@@ -39,7 +39,12 @@ export default function MenuListExample() {
 }
 
 function MenuList({ file }: { file: RiveFile }) {
-  const instance = useViewModelInstance(file, { required: true });
+  const { instance, error } = useViewModelInstance(file);
+
+  if (error) {
+    console.error(error.message);
+    return <Text style={{ color: 'red' }}>{error.message}</Text>;
+  }
 
   if (!instance) {
     return <ActivityIndicator size="large" color="#007AFF" />;

example/src/exercisers/NestedViewModelExample.tsx

@@ -38,7 +38,12 @@ export default function NestedViewModelExample() {
 }
 
 function WithViewModelSetup({ file }: { file: RiveFile }) {
-  const instance = useViewModelInstance(file);
+  const { instance, error } = useViewModelInstance(file);
+
+  if (error) {
+    console.error(error.message);
+    return <Text style={{ color: 'red' }}>{error.message}</Text>;
+  }
 
   if (!instance) {
     return <ActivityIndicator size="large" color="#0000ff" />;

example/src/exercisers/RiveDataBindingExample.tsx

@@ -35,7 +35,12 @@ export default function WithRiveFile() {
 }
 
 function WithViewModelSetup({ file }: { file: RiveFile }) {
-  const instance = useViewModelInstance(file);
+  const { instance, error } = useViewModelInstance(file);
+
+  if (error) {
+    console.error(error.message);
+    return <Text style={{ color: 'red' }}>{error.message}</Text>;
+  }
 
   if (!instance) {
     return <ActivityIndicator size="large" color="#0000ff" />;

src/hooks/__tests__/useRiveProperty.test.ts

@@ -17,6 +17,9 @@ describe('useRiveProperty', () => {
       },
       addListener: jest.fn((callback: (value: string) => void) => {
         listener = callback;
+        // Emit the current value immediately on subscribe, matching native behaviour:
+        // iOS legacy emits synchronously; experimental backend emits via valueStream.
+        callback(currentValue);
         return () => {
           listener = null;
         };
@@ -36,7 +39,9 @@ describe('useRiveProperty', () => {
     } as unknown as ViewModelInstance;
   };
 
-  it('should return initial value from property on first render', () => {
+  it('should return initial value delivered via listener (not from a sync read)', () => {
+    // Hooks always start undefined; the listener emits the current value immediately
+    // on subscribe (synchronously for legacy, via stream for experimental).
     const mockProperty = createMockProperty('Tea');
     const mockInstance = createMockViewModelInstance({
       'favDrink/type': mockProperty,
@@ -48,6 +53,8 @@ describe('useRiveProperty', () => {
       })
     );
 
+    // The mock's addListener emits 'Tea' synchronously — React batches it with the
+    // effect, so the value is available after renderHook (which wraps in act()).
     const [value] = result.current;
     expect(value).toBe('Tea');
   });

src/hooks/__tests__/useViewModelInstance.test.ts

@@ -86,7 +86,8 @@ describe('useViewModelInstance - RiveFile with instanceName parameter', () => {
       'PersonInstance'
     );
     expect(defaultViewModel.createDefaultInstance).not.toHaveBeenCalled();
-    expect(result.current).toBe(personInstance);
+    expect(result.current.instance).toBe(personInstance);
+    expect(result.current.error).toBeNull();
   });
 
   it('should use defaultArtboardViewModel and createDefaultInstance when no instanceName provided', () => {
@@ -102,10 +103,11 @@ describe('useViewModelInstance - RiveFile with instanceName parameter', () => {
     );
     expect(defaultViewModel.createDefaultInstance).toHaveBeenCalled();
     expect(defaultViewModel.createInstanceByName).not.toHaveBeenCalled();
-    expect(result.current).toBe(defaultInstance);
+    expect(result.current.instance).toBe(defaultInstance);
+    expect(result.current.error).toBeNull();
   });
 
-  it('should return null when instance name not found and required is false', () => {
+  it('should return error when instance name not found and required is false', () => {
     const defaultViewModel = createMockViewModel({
       namedInstances: {},
     });
@@ -116,7 +118,9 @@ describe('useViewModelInstance - RiveFile with instanceName parameter', () => {
       useViewModelInstance(mockRiveFile, { instanceName: 'NonExistent' })
     );
 
-    expect(result.current).toBeNull();
+    expect(result.current.instance).toBeNull();
+    expect(result.current.error).toBeInstanceOf(Error);
+    expect(result.current.error?.message).toContain('NonExistent');
   });
 
   it('should throw when instance name not found and required is true', () => {
@@ -136,7 +140,7 @@ describe('useViewModelInstance - RiveFile with instanceName parameter', () => {
     ).toThrow("ViewModel instance 'NonExistent' not found");
   });
 
-  it('should return null when artboardName not found and required is false', () => {
+  it('should return error when artboardName not found and required is false', () => {
     const mockRiveFile = createMockRiveFile({
       artboardViewModels: {},
     });
@@ -145,7 +149,9 @@ describe('useViewModelInstance - RiveFile with instanceName parameter', () => {
       useViewModelInstance(mockRiveFile, { artboardName: 'MissingArtboard' })
     );
 
-    expect(result.current).toBeNull();
+    expect(result.current.instance).toBeNull();
+    expect(result.current.error).toBeInstanceOf(Error);
+    expect(result.current.error?.message).toContain('MissingArtboard');
   });
 
   it('should throw when artboardName not found and required is true', () => {
@@ -203,7 +209,8 @@ describe('useViewModelInstance - RiveFile with artboardName parameter', () => {
       name: 'MainArtboard',
     });
     expect(mainArtboardViewModel.createDefaultInstance).toHaveBeenCalled();
-    expect(result.current).toBe(mainInstance);
+    expect(result.current.instance).toBe(mainInstance);
+    expect(result.current.error).toBeNull();
   });
 
   it('should combine artboardName and instanceName to get specific instance from specific artboard', () => {
@@ -230,7 +237,8 @@ describe('useViewModelInstance - RiveFile with artboardName parameter', () => {
     expect(mainArtboardViewModel.createInstanceByName).toHaveBeenCalledWith(
       'SpecificInstance'
     );
-    expect(result.current).toBe(specificInstance);
+    expect(result.current.instance).toBe(specificInstance);
+    expect(result.current.error).toBeNull();
   });
 });
 
@@ -252,10 +260,11 @@ describe('useViewModelInstance - RiveFile with viewModelName parameter', () => {
     expect(mockRiveFile.viewModelByName).toHaveBeenCalledWith('Settings');
     expect(mockRiveFile.defaultArtboardViewModel).not.toHaveBeenCalled();
     expect(settingsViewModel.createDefaultInstance).toHaveBeenCalled();
-    expect(result.current).toBe(settingsInstance);
+    expect(result.current.instance).toBe(settingsInstance);
+    expect(result.current.error).toBeNull();
   });
 
-  it('should return null when viewModelName not found and required is false', () => {
+  it('should return error when viewModelName not found and required is false', () => {
     const mockRiveFile = createMockRiveFile({
       namedViewModels: {},
     });
@@ -264,7 +273,9 @@ describe('useViewModelInstance - RiveFile with viewModelName parameter', () => {
       useViewModelInstance(mockRiveFile, { viewModelName: 'NonExistent' })
     );
 
-    expect(result.current).toBeNull();
+    expect(result.current.instance).toBeNull();
+    expect(result.current.error).toBeInstanceOf(Error);
+    expect(result.current.error?.message).toContain('NonExistent');
   });
 
   it('should throw when viewModelName not found and required is true', () => {
@@ -303,7 +314,8 @@ describe('useViewModelInstance - RiveFile with viewModelName parameter', () => {
     expect(settingsViewModel.createInstanceByName).toHaveBeenCalledWith(
       'UserSettings'
     );
-    expect(result.current).toBe(specificInstance);
+    expect(result.current.instance).toBe(specificInstance);
+    expect(result.current.error).toBeNull();
   });
 });
 
@@ -320,7 +332,8 @@ describe('useViewModelInstance - ViewModel source', () => {
 
     expect(mockViewModel.createInstanceByName).toHaveBeenCalledWith('Gordon');
     expect(mockViewModel.createDefaultInstance).not.toHaveBeenCalled();
-    expect(result.current).toBe(namedInstance);
+    expect(result.current.instance).toBe(namedInstance);
+    expect(result.current.error).toBeNull();
   });
 
   it('should use createInstance when useNew is true', () => {
@@ -334,7 +347,8 @@ describe('useViewModelInstance - ViewModel source', () => {
 
     expect(mockViewModel.createInstance).toHaveBeenCalled();
     expect(mockViewModel.createDefaultInstance).not.toHaveBeenCalled();
-    expect(result.current).toBe(newInstance);
+    expect(result.current.instance).toBe(newInstance);
+    expect(result.current.error).toBeNull();
   });
 
   it('should use createDefaultInstance when no params provided', () => {
@@ -344,6 +358,16 @@ describe('useViewModelInstance - ViewModel source', () => {
     const { result } = renderHook(() => useViewModelInstance(mockViewModel));
 
     expect(mockViewModel.createDefaultInstance).toHaveBeenCalled();
-    expect(result.current).toBe(defaultInstance);
+    expect(result.current.instance).toBe(defaultInstance);
+    expect(result.current.error).toBeNull();
+  });
+});
+
+describe('useViewModelInstance - null source', () => {
+  it('should return undefined instance when source is null', () => {
+    const { result } = renderHook(() => useViewModelInstance(null));
+
+    expect(result.current.instance).toBeUndefined();
+    expect(result.current.error).toBeNull();
   });
 });

src/hooks/useRiveProperty.ts

@@ -34,7 +34,6 @@ export function useRiveProperty<P extends ViewModelProperty, T>(
   Error | null,
   P | undefined,
 ] {
-  // Get the property first so we can read its initial value
   const property = useMemo(() => {
     if (!viewModelInstance) return;
     return options.getProperty(
@@ -43,17 +42,12 @@ export function useRiveProperty<P extends ViewModelProperty, T>(
     ) as unknown as ObservableViewModelProperty<T>;
   }, [options, viewModelInstance, path]);
 
-  // Initialize state with property's current value (if available)
-  const [value, setValue] = useState<T | undefined>(() => property?.value);
+  // Always start undefined — the listener delivers the current value as its first emission.
+  // (iOS experimental: via valueStream; iOS/Android legacy: emitted synchronously on subscribe)
+  // This ensures consumers handle the loading state correctly on all backends.
+  const [value, setValue] = useState<T | undefined>(undefined);
   const [error, setError] = useState<Error | null>(null);
 
-  // Sync value when property reference changes (path or instance changed)
-  useEffect(() => {
-    if (property) {
-      setValue(property.value);
-    }
-  }, [property]);
-
   // Clear error when path or instance changes
   useEffect(() => {
     setError(null);
@@ -72,8 +66,14 @@ export function useRiveProperty<P extends ViewModelProperty, T>(
   useEffect(() => {
     if (!property) return;
 
-    // If an override callback is provided, use it.
-    // Otherwise, use the default callback.
+    // Deliver the current value immediately so the hook transitions from
+    // undefined → value without waiting for a property change.
+    // (Legacy addListener does NOT emit on subscribe — only on changes.
+    //  Experimental valueStream emits the current value as its first element.)
+    if (!options.onPropertyEventOverride) {
+      setValue(property.value);
+    }
+
     const removeListener = options.onPropertyEventOverride
       ? property.addListener(options.onPropertyEventOverride)
       : property.addListener((newValue) => {
@@ -86,22 +86,22 @@ export function useRiveProperty<P extends ViewModelProperty, T>(
     };
   }, [options, property]);
 
-  // Set the value of the property (no-op if property isn't available yet)
+  // Set the value of the property (no-op if property isn't available yet).
+  // Uses tracked `value` from state for updater functions — avoids a synchronous
+  // property.value read and is consistent with how React state works.
   const setPropertyValue = useCallback(
     (valueOrUpdater: T | ((prevValue: T | undefined) => T)) => {
       if (!property) {
         return;
       } else {
         const newValue =
           typeof valueOrUpdater === 'function'
-            ? (valueOrUpdater as (prevValue: T | undefined) => T)(
-                property.value
-              )
+            ? (valueOrUpdater as (prevValue: T | undefined) => T)(value)
             : valueOrUpdater;
         property.value = newValue;
       }
     },
-    [property]
+    [property, value]
   );
 
   return [value, setPropertyValue, error, property as unknown as P];