fix!: useViewModelInstance returns { instance, error } instead of instance | null

Consumers can now distinguish between no-source (instance: null, error: null),
lookup error (instance: null, error: string), and success (instance: VMI, error: null).

Author: mfazekas

example/__tests__/hooks.harness.tsx

@@ -70,7 +70,7 @@ function UseViewModelInstanceTestComponent({
   file: RiveFile;
   context: UseViewModelInstanceContext;
 }) {
-  const instance = useViewModelInstance(file);
+  const { instance } = useViewModelInstance(file);
 
   const age = useMemo(() => {
     if (!instance) return undefined;

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/MenuListExample.tsx

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

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,7 +103,8 @@ 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', () => {
@@ -116,7 +118,8 @@ describe('useViewModelInstance - RiveFile with instanceName parameter', () => {
       useViewModelInstance(mockRiveFile, { instanceName: 'NonExistent' })
     );
 
-    expect(result.current).toBeNull();
+    expect(result.current.instance).toBeNull();
+    expect(result.current.error).toContain('not found');
   });
 
   it('should throw when instance name not found and required is true', () => {
@@ -145,7 +148,8 @@ describe('useViewModelInstance - RiveFile with instanceName parameter', () => {
       useViewModelInstance(mockRiveFile, { artboardName: 'MissingArtboard' })
     );
 
-    expect(result.current).toBeNull();
+    expect(result.current.instance).toBeNull();
+    expect(result.current.error).toContain('not found');
   });
 
   it('should throw when artboardName not found and required is true', () => {
@@ -203,7 +207,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 +235,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,7 +258,8 @@ 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', () => {
@@ -264,7 +271,8 @@ describe('useViewModelInstance - RiveFile with viewModelName parameter', () => {
       useViewModelInstance(mockRiveFile, { viewModelName: 'NonExistent' })
     );
 
-    expect(result.current).toBeNull();
+    expect(result.current.instance).toBeNull();
+    expect(result.current.error).toContain('not found');
   });
 
   it('should throw when viewModelName not found and required is true', () => {
@@ -303,7 +311,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 +329,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 +344,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 +355,7 @@ 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();
   });
 });

src/hooks/useViewModelInstance.ts

@@ -176,73 +176,78 @@ function createInstance(
   return { instance: vmi ?? null, needsDispose: true };
 }
 
+export type UseViewModelInstanceResult = {
+  instance: ViewModelInstance | null;
+  error: string | null;
+};
+
 /**
  * Hook for getting a ViewModelInstance from a RiveFile, ViewModel, or RiveViewRef.
  *
  * @param source - The RiveFile, ViewModel, or RiveViewRef to get an instance from
  * @param params - Configuration for which instance to retrieve
- * @returns The ViewModelInstance or null if not found
+ * @returns An object with `instance` (the ViewModelInstance or null) and `error` (string or null)
  *
  * @example
  * ```tsx
  * // From RiveFile (get default instance)
  * const { riveFile } = useRiveFile(require('./animation.riv'));
- * const instance = useViewModelInstance(riveFile);
+ * const { instance } = useViewModelInstance(riveFile);
  * ```
  *
  * @example
  * ```tsx
  * // From RiveFile with specific instance name
  * const { riveFile } = useRiveFile(require('./animation.riv'));
- * const instance = useViewModelInstance(riveFile, { instanceName: 'PersonInstance' });
+ * const { instance } = useViewModelInstance(riveFile, { instanceName: 'PersonInstance' });
  * ```
  *
  * @example
  * ```tsx
  * // From RiveFile with specific ViewModel name
  * const { riveFile } = useRiveFile(require('./animation.riv'));
- * const instance = useViewModelInstance(riveFile, { viewModelName: 'Settings' });
+ * const { instance } = useViewModelInstance(riveFile, { viewModelName: 'Settings' });
  * ```
  *
  * @example
  * ```tsx
  * // From RiveFile with specific artboard
  * const { riveFile } = useRiveFile(require('./animation.riv'));
- * const instance = useViewModelInstance(riveFile, { artboardName: 'MainArtboard' });
+ * const { instance } = useViewModelInstance(riveFile, { artboardName: 'MainArtboard' });
  * ```
  *
  * @example
  * ```tsx
  * // From RiveViewRef (get auto-bound instance)
  * const { riveViewRef, setHybridRef } = useRive();
- * const instance = useViewModelInstance(riveViewRef);
+ * const { instance } = useViewModelInstance(riveViewRef);
  * ```
  *
  * @example
  * ```tsx
  * // From ViewModel
  * const viewModel = file.viewModelByName('main');
- * const instance = useViewModelInstance(viewModel);
+ * const { instance } = useViewModelInstance(viewModel);
  * ```
  *
  * @example
  * ```tsx
  * // Create a new blank instance from ViewModel
  * const viewModel = file.viewModelByName('TodoItem');
- * const newInstance = useViewModelInstance(viewModel, { useNew: true });
+ * const { instance: newInstance } = useViewModelInstance(viewModel, { useNew: true });
  * ```
  *
  * @example
  * ```tsx
  * // With required: true (throws if null, use with Error Boundary)
- * const instance = useViewModelInstance(riveFile, { required: true });
+ * const { instance } = useViewModelInstance(riveFile, { required: true });
  * // instance is guaranteed to be non-null here
  * ```
  *
  * @example
  * ```tsx
  * // With onInit to set initial values synchronously
- * const instance = useViewModelInstance(riveFile, {
+ * const { instance } = useViewModelInstance(riveFile, {
  *   onInit: (vmi) => {
  *     vmi.numberProperty('count').set(initialCount);
  *     vmi.stringProperty('name').set(userName);
@@ -255,31 +260,31 @@ function createInstance(
 export function useViewModelInstance(
   source: RiveFile,
   params: UseViewModelInstanceFileParams & { required: true }
-): ViewModelInstance;
+): { instance: ViewModelInstance; error: null };
 export function useViewModelInstance(
   source: RiveFile | null,
   params?: UseViewModelInstanceFileParams
-): ViewModelInstance | null;
+): UseViewModelInstanceResult;
 
 // ViewModel overloads
 export function useViewModelInstance(
   source: ViewModel,
   params: UseViewModelInstanceViewModelParams & { required: true }
-): ViewModelInstance;
+): { instance: ViewModelInstance; error: null };
 export function useViewModelInstance(
   source: ViewModel | null,
   params?: UseViewModelInstanceViewModelParams
-): ViewModelInstance | null;
+): UseViewModelInstanceResult;
 
 // RiveViewRef overloads
 export function useViewModelInstance(
   source: RiveViewRef,
   params: UseViewModelInstanceRefParams & { required: true }
-): ViewModelInstance;
+): { instance: ViewModelInstance; error: null };
 export function useViewModelInstance(
   source: RiveViewRef | null,
   params?: UseViewModelInstanceRefParams
-): ViewModelInstance | null;
+): UseViewModelInstanceResult;
 
 // Implementation
 export function useViewModelInstance(
@@ -288,7 +293,7 @@ export function useViewModelInstance(
     | UseViewModelInstanceFileParams
     | UseViewModelInstanceViewModelParams
     | UseViewModelInstanceRefParams
-): ViewModelInstance | null {
+): UseViewModelInstanceResult {
   const fileInstanceName = (params as { instanceName?: string } | undefined)
     ?.instanceName;
   const viewModelInstanceName = (params as { name?: string } | undefined)?.name;
@@ -356,5 +361,5 @@ export function useViewModelInstance(
     );
   }
 
-  return result.instance;
+  return { instance: result.instance, error: result.error ?? null };
 }

src/index.tsx

@@ -58,7 +58,10 @@ export { useRiveEnum } from './hooks/useRiveEnum';
 export { useRiveColor } from './hooks/useRiveColor';
 export { useRiveTrigger } from './hooks/useRiveTrigger';
 export { useRiveList } from './hooks/useRiveList';
-export { useViewModelInstance } from './hooks/useViewModelInstance';
+export {
+  useViewModelInstance,
+  type UseViewModelInstanceResult,
+} from './hooks/useViewModelInstance';
 export { useRiveFile } from './hooks/useRiveFile';
 export { type RiveFileInput } from './hooks/useRiveFile';
 export { type SetValueAction } from './types';