@rive-app/react-native 0.2.0 → 0.2.2

package/lib/module/hooks/useViewModelInstance.js.map

@@ -1 +1 @@
-{"version":3,"names":["useMemo","useEffect","useRef","callDispose","isRiveViewRef","source","undefined","isRiveFile","createInstance","name","useNew","instance","needsDispose","vmi","getViewModelInstance","viewModel","defaultArtboardViewModel","createDefaultInstance","createInstanceByName","useViewModelInstance","params","required","onInit","prevInstanceRef","result","created","current","Error"],"sourceRoot":"../../../src","sources":["hooks/useViewModelInstance.ts"],"mappings":"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","ignoreList":[]}
+{"version":3,"names":["useMemo","useEffect","useRef","callDispose","ArtboardByName","isRiveViewRef","source","isRiveFile","createInstance","instanceName","artboardName","viewModelName","useNew","instance","needsDispose","vmi","getViewModelInstance","viewModel","viewModelByName","error","defaultArtboardViewModel","undefined","createInstanceByName","createDefaultInstance","useViewModelInstance","params","fileInstanceName","viewModelInstanceName","name","required","onInit","prevInstanceRef","result","created","current","Error"],"sourceRoot":"../../../src","sources":["hooks/useViewModelInstance.ts"],"mappings":"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","ignoreList":[]}

package/lib/typescript/src/hooks/useRiveEnum.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useRiveEnum.d.ts","sourceRoot":"","sources":["../../../../src/hooks/useRiveEnum.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAGtD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,IAAI,GAC3C,qBAAqB,CAAC,MAAM,CAAC,CAQ/B"}
+{"version":3,"file":"useRiveEnum.d.ts","sourceRoot":"","sources":["../../../../src/hooks/useRiveEnum.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAOtD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,iBAAiB,CAAC,EAAE,iBAAiB,GAAG,IAAI,GAC3C,qBAAqB,CAAC,MAAM,CAAC,CAM/B"}

package/lib/typescript/src/hooks/useViewModelInstance.d.ts

@@ -1,15 +1,7 @@
 import type { ViewModel, ViewModelInstance } from '../specs/ViewModel.nitro';
 import type { RiveFile } from '../specs/RiveFile.nitro';
 import type { RiveViewRef } from '../index';
-export interface UseViewModelInstanceParams {
-    /**
-     * Get a specifically named instance from the ViewModel.
-     */
-    name?: string;
-    /**
-     * Create a new (blank) instance from the ViewModel.
-     */
-    useNew?: boolean;
+interface UseViewModelInstanceBaseParams {
     /**
      * If true, throws an error when the instance cannot be obtained.
      * This is useful with Error Boundaries and ensures TypeScript knows
@@ -23,12 +15,60 @@ export interface UseViewModelInstanceParams {
      */
     onInit?: (instance: ViewModelInstance) => void;
 }
-type ViewModelSource = ViewModel | RiveFile | RiveViewRef;
+interface UseViewModelInstanceFileBaseParams extends UseViewModelInstanceBaseParams {
+    /**
+     * The ViewModel instance name (uses `createInstanceByName()`).
+     * If not provided, creates the default instance.
+     */
+    instanceName?: string;
+}
+/**
+ * Use the ViewModel assigned to the default artboard.
+ */
+interface UseViewModelInstanceFileDefault extends UseViewModelInstanceFileBaseParams {
+    artboardName?: never;
+    viewModelName?: never;
+}
+/**
+ * Use the ViewModel assigned to a specific artboard.
+ */
+interface UseViewModelInstanceFileByArtboard extends UseViewModelInstanceFileBaseParams {
+    /**
+     * Get the ViewModel assigned to this artboard.
+     */
+    artboardName: string;
+    viewModelName?: never;
+}
+/**
+ * Use a ViewModel by name (file-wide lookup).
+ * ViewModels are defined at the file level, not per-artboard.
+ */
+interface UseViewModelInstanceFileByViewModelName extends UseViewModelInstanceFileBaseParams {
+    artboardName?: never;
+    /**
+     * The name of the ViewModel to use (uses `viewModelByName()`).
+     * ViewModels are defined at the file level and looked up by name across the entire file.
+     */
+    viewModelName: string;
+}
+export type UseViewModelInstanceFileParams = UseViewModelInstanceFileDefault | UseViewModelInstanceFileByArtboard | UseViewModelInstanceFileByViewModelName;
+export interface UseViewModelInstanceViewModelParams extends UseViewModelInstanceBaseParams {
+    /**
+     * The ViewModel instance name (uses `createInstanceByName()`).
+     * If not provided, creates the default instance.
+     */
+    name?: string;
+    /**
+     * Create a new (blank) instance from the ViewModel.
+     */
+    useNew?: boolean;
+}
+export type UseViewModelInstanceRefParams = UseViewModelInstanceBaseParams;
 /**
  * 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 (only used with ViewModel)
+ * @param params - Configuration for which instance to retrieve
  * @returns The ViewModelInstance or null if not found
  *
  * @example
@@ -40,6 +80,27 @@ type ViewModelSource = ViewModel | RiveFile | RiveViewRef;
  *
  * @example
  * ```tsx
+ * // From RiveFile with specific instance name
+ * const { riveFile } = useRiveFile(require('./animation.riv'));
+ * 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' });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // From RiveFile with specific artboard
+ * const { riveFile } = useRiveFile(require('./animation.riv'));
+ * const instance = useViewModelInstance(riveFile, { artboardName: 'MainArtboard' });
+ * ```
+ *
+ * @example
+ * ```tsx
  * // From RiveViewRef (get auto-bound instance)
  * const { riveViewRef, setHybridRef } = useRive();
  * const instance = useViewModelInstance(riveViewRef);
@@ -78,9 +139,17 @@ type ViewModelSource = ViewModel | RiveFile | RiveViewRef;
  * // Values are already set here
  * ```
  */
-export declare function useViewModelInstance(source: ViewModelSource, params: UseViewModelInstanceParams & {
+export declare function useViewModelInstance(source: RiveFile, params: UseViewModelInstanceFileParams & {
+    required: true;
+}): ViewModelInstance;
+export declare function useViewModelInstance(source: RiveFile | null, params?: UseViewModelInstanceFileParams): ViewModelInstance | null;
+export declare function useViewModelInstance(source: ViewModel, params: UseViewModelInstanceViewModelParams & {
+    required: true;
+}): ViewModelInstance;
+export declare function useViewModelInstance(source: ViewModel | null, params?: UseViewModelInstanceViewModelParams): ViewModelInstance | null;
+export declare function useViewModelInstance(source: RiveViewRef, params: UseViewModelInstanceRefParams & {
     required: true;
 }): ViewModelInstance;
-export declare function useViewModelInstance(source: ViewModelSource | null, params?: UseViewModelInstanceParams): ViewModelInstance | null;
+export declare function useViewModelInstance(source: RiveViewRef | null, params?: UseViewModelInstanceRefParams): ViewModelInstance | null;
 export {};
 //# sourceMappingURL=useViewModelInstance.d.ts.map

package/lib/typescript/src/hooks/useViewModelInstance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useViewModelInstance.d.ts","sourceRoot":"","sources":["../../../../src/hooks/useViewModelInstance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5C,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAChD;AAED,KAAK,eAAe,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAgD1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,0BAA0B,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GACtD,iBAAiB,CAAC;AACrB,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,eAAe,GAAG,IAAI,EAC9B,MAAM,CAAC,EAAE,0BAA0B,GAClC,iBAAiB,GAAG,IAAI,CAAC"}
+{"version":3,"file":"useViewModelInstance.d.ts","sourceRoot":"","sources":["../../../../src/hooks/useViewModelInstance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAI5C,UAAU,8BAA8B;IACtC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAChD;AAED,UAAU,kCACR,SAAQ,8BAA8B;IACtC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,UAAU,+BACR,SAAQ,kCAAkC;IAC1C,YAAY,CAAC,EAAE,KAAK,CAAC;IACrB,aAAa,CAAC,EAAE,KAAK,CAAC;CACvB;AAED;;GAEG;AACH,UAAU,kCACR,SAAQ,kCAAkC;IAC1C;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,KAAK,CAAC;CACvB;AAED;;;GAGG;AACH,UAAU,uCACR,SAAQ,kCAAkC;IAC1C,YAAY,CAAC,EAAE,KAAK,CAAC;IACrB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,8BAA8B,GACtC,+BAA+B,GAC/B,kCAAkC,GAClC,uCAAuC,CAAC;AAE5C,MAAM,WAAW,mCACf,SAAQ,8BAA8B;IACtC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,6BAA6B,GAAG,8BAA8B,CAAC;AA4F3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,QAAQ,EAChB,MAAM,EAAE,8BAA8B,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAC1D,iBAAiB,CAAC;AACrB,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,QAAQ,GAAG,IAAI,EACvB,MAAM,CAAC,EAAE,8BAA8B,GACtC,iBAAiB,GAAG,IAAI,CAAC;AAG5B,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,mCAAmC,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAC/D,iBAAiB,CAAC;AACrB,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,GAAG,IAAI,EACxB,MAAM,CAAC,EAAE,mCAAmC,GAC3C,iBAAiB,GAAG,IAAI,CAAC;AAG5B,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,6BAA6B,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GACzD,iBAAiB,CAAC;AACrB,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,WAAW,GAAG,IAAI,EAC1B,MAAM,CAAC,EAAE,6BAA6B,GACrC,iBAAiB,GAAG,IAAI,CAAC"}

package/lib/typescript/src/specs/RiveView.nitro.d.ts

@@ -19,7 +19,7 @@ export interface DataBindByName {
 export interface RiveViewProps extends HybridViewProps {
     /** Name of the artboard to display from the Rive file */
     artboardName?: string;
-    /** Name of the state mgachine to play */
+    /** Name of the state machine to play */
     stateMachineName?: string;
     /** Whether to automatically start playing the state machine */
     autoPlay?: boolean;

package/lib/typescript/src/specs/RiveView.nitro.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RiveView.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/RiveView.nitro.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"RiveView.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/RiveView.nitro.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rive-app/react-native",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Rive React Native",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -84,6 +84,7 @@
     "@types/react": "^19.0.0",
     "@typescript-eslint/eslint-plugin": "^8.46.4",
     "@typescript-eslint/parser": "^8.46.4",
+    "babel-plugin-react-compiler": "^1.0.0",
     "commitlint": "^19.6.1",
     "del-cli": "^5.1.0",
     "eslint": "^9.22.0",
@@ -167,7 +168,8 @@
       [
         "module",
         {
-          "esm": true
+          "esm": true,
+          "configFile": true
         }
       ],
       [

package/src/hooks/useRiveEnum.ts

@@ -1,4 +1,3 @@
-import { useCallback } from 'react';
 import {
   type ViewModelEnumProperty,
   type ViewModelInstance,
@@ -6,6 +5,10 @@ import {
 import type { UseRivePropertyResult } from '../types';
 import { useRiveProperty } from './useRiveProperty';
 
+const ENUM_PROPERTY_OPTIONS = {
+  getProperty: (vmi: ViewModelInstance, p: string) => vmi.enumProperty(p),
+};
+
 /**
  * Hook for interacting with enum ViewModel instance properties.
  *
@@ -20,8 +23,6 @@ export function useRiveEnum(
   const [value, setValue, error] = useRiveProperty<
     ViewModelEnumProperty,
     string
-  >(viewModelInstance, path, {
-    getProperty: useCallback((vmi, p) => vmi.enumProperty(p), []),
-  });
+  >(viewModelInstance, path, ENUM_PROPERTY_OPTIONS);
   return { value, setValue, error };
 }

package/src/hooks/useViewModelInstance.ts

@@ -3,16 +3,9 @@ import type { ViewModel, ViewModelInstance } from '../specs/ViewModel.nitro';
 import type { RiveFile } from '../specs/RiveFile.nitro';
 import type { RiveViewRef } from '../index';
 import { callDispose } from '../core/callDispose';
+import { ArtboardByName } from '../specs/ArtboardBy';
 
-export interface UseViewModelInstanceParams {
-  /**
-   * Get a specifically named instance from the ViewModel.
-   */
-  name?: string;
-  /**
-   * Create a new (blank) instance from the ViewModel.
-   */
-  useNew?: boolean;
+interface UseViewModelInstanceBaseParams {
   /**
    * If true, throws an error when the instance cannot be obtained.
    * This is useful with Error Boundaries and ensures TypeScript knows
@@ -27,27 +20,93 @@ export interface UseViewModelInstanceParams {
   onInit?: (instance: ViewModelInstance) => void;
 }
 
+interface UseViewModelInstanceFileBaseParams
+  extends UseViewModelInstanceBaseParams {
+  /**
+   * The ViewModel instance name (uses `createInstanceByName()`).
+   * If not provided, creates the default instance.
+   */
+  instanceName?: string;
+}
+
+/**
+ * Use the ViewModel assigned to the default artboard.
+ */
+interface UseViewModelInstanceFileDefault
+  extends UseViewModelInstanceFileBaseParams {
+  artboardName?: never;
+  viewModelName?: never;
+}
+
+/**
+ * Use the ViewModel assigned to a specific artboard.
+ */
+interface UseViewModelInstanceFileByArtboard
+  extends UseViewModelInstanceFileBaseParams {
+  /**
+   * Get the ViewModel assigned to this artboard.
+   */
+  artboardName: string;
+  viewModelName?: never;
+}
+
+/**
+ * Use a ViewModel by name (file-wide lookup).
+ * ViewModels are defined at the file level, not per-artboard.
+ */
+interface UseViewModelInstanceFileByViewModelName
+  extends UseViewModelInstanceFileBaseParams {
+  artboardName?: never;
+  /**
+   * The name of the ViewModel to use (uses `viewModelByName()`).
+   * ViewModels are defined at the file level and looked up by name across the entire file.
+   */
+  viewModelName: string;
+}
+
+export type UseViewModelInstanceFileParams =
+  | UseViewModelInstanceFileDefault
+  | UseViewModelInstanceFileByArtboard
+  | UseViewModelInstanceFileByViewModelName;
+
+export interface UseViewModelInstanceViewModelParams
+  extends UseViewModelInstanceBaseParams {
+  /**
+   * The ViewModel instance name (uses `createInstanceByName()`).
+   * If not provided, creates the default instance.
+   */
+  name?: string;
+  /**
+   * Create a new (blank) instance from the ViewModel.
+   */
+  useNew?: boolean;
+}
+
+export type UseViewModelInstanceRefParams = UseViewModelInstanceBaseParams;
+
 type ViewModelSource = ViewModel | RiveFile | RiveViewRef;
 
 function isRiveViewRef(source: ViewModelSource | null): source is RiveViewRef {
-  return (
-    source !== null && source !== undefined && 'getViewModelInstance' in source
-  );
+  return source !== null && 'getViewModelInstance' in source;
 }
 
 function isRiveFile(source: ViewModelSource | null): source is RiveFile {
-  return (
-    source !== null &&
-    source !== undefined &&
-    'defaultArtboardViewModel' in source
-  );
+  return source !== null && 'defaultArtboardViewModel' in source;
 }
 
+type CreateInstanceResult = {
+  instance: ViewModelInstance | null;
+  needsDispose: boolean;
+  error?: string;
+};
+
 function createInstance(
   source: ViewModelSource | null,
-  name: string | undefined,
+  instanceName: string | undefined,
+  artboardName: string | undefined,
+  viewModelName: string | undefined,
   useNew: boolean
-): { instance: ViewModelInstance | null; needsDispose: boolean } {
+): CreateInstanceResult {
   if (!source) {
     return { instance: null, needsDispose: false };
   }
@@ -58,15 +117,55 @@ function createInstance(
   }
 
   if (isRiveFile(source)) {
-    const viewModel = source.defaultArtboardViewModel();
-    const vmi = viewModel?.createDefaultInstance();
+    let viewModel: ViewModel | undefined;
+    if (viewModelName) {
+      viewModel = source.viewModelByName(viewModelName);
+      if (!viewModel) {
+        return {
+          instance: null,
+          needsDispose: false,
+          error: `ViewModel '${viewModelName}' not found`,
+        };
+      }
+    } else {
+      viewModel = source.defaultArtboardViewModel(
+        artboardName ? ArtboardByName(artboardName) : undefined
+      );
+      if (!viewModel) {
+        if (artboardName) {
+          return {
+            instance: null,
+            needsDispose: false,
+            error: `Artboard '${artboardName}' not found or has no ViewModel`,
+          };
+        }
+        return { instance: null, needsDispose: false };
+      }
+    }
+    const vmi = instanceName
+      ? viewModel.createInstanceByName(instanceName)
+      : viewModel.createDefaultInstance();
+    if (!vmi && instanceName) {
+      return {
+        instance: null,
+        needsDispose: false,
+        error: `ViewModel instance '${instanceName}' not found`,
+      };
+    }
     return { instance: vmi ?? null, needsDispose: true };
   }
 
   // ViewModel source
   let vmi: ViewModelInstance | undefined;
-  if (name) {
-    vmi = source.createInstanceByName(name);
+  if (instanceName) {
+    vmi = source.createInstanceByName(instanceName);
+    if (!vmi) {
+      return {
+        instance: null,
+        needsDispose: false,
+        error: `ViewModel instance '${instanceName}' not found`,
+      };
+    }
   } else if (useNew) {
     vmi = source.createInstance();
   } else {
@@ -79,7 +178,7 @@ function createInstance(
  * 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 (only used with ViewModel)
+ * @param params - Configuration for which instance to retrieve
  * @returns The ViewModelInstance or null if not found
  *
  * @example
@@ -91,6 +190,27 @@ function createInstance(
  *
  * @example
  * ```tsx
+ * // From RiveFile with specific instance name
+ * const { riveFile } = useRiveFile(require('./animation.riv'));
+ * 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' });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // From RiveFile with specific artboard
+ * const { riveFile } = useRiveFile(require('./animation.riv'));
+ * const instance = useViewModelInstance(riveFile, { artboardName: 'MainArtboard' });
+ * ```
+ *
+ * @example
+ * ```tsx
  * // From RiveViewRef (get auto-bound instance)
  * const { riveViewRef, setHybridRef } = useRive();
  * const instance = useViewModelInstance(riveViewRef);
@@ -129,20 +249,55 @@ function createInstance(
  * // Values are already set here
  * ```
  */
+// RiveFile overloads
 export function useViewModelInstance(
-  source: ViewModelSource,
-  params: UseViewModelInstanceParams & { required: true }
+  source: RiveFile,
+  params: UseViewModelInstanceFileParams & { required: true }
 ): ViewModelInstance;
 export function useViewModelInstance(
-  source: ViewModelSource | null,
-  params?: UseViewModelInstanceParams
+  source: RiveFile | null,
+  params?: UseViewModelInstanceFileParams
+): ViewModelInstance | null;
+
+// ViewModel overloads
+export function useViewModelInstance(
+  source: ViewModel,
+  params: UseViewModelInstanceViewModelParams & { required: true }
+): ViewModelInstance;
+export function useViewModelInstance(
+  source: ViewModel | null,
+  params?: UseViewModelInstanceViewModelParams
 ): ViewModelInstance | null;
+
+// RiveViewRef overloads
+export function useViewModelInstance(
+  source: RiveViewRef,
+  params: UseViewModelInstanceRefParams & { required: true }
+): ViewModelInstance;
+export function useViewModelInstance(
+  source: RiveViewRef | null,
+  params?: UseViewModelInstanceRefParams
+): ViewModelInstance | null;
+
+// Implementation
 export function useViewModelInstance(
   source: ViewModelSource | null,
-  params?: UseViewModelInstanceParams
+  params?:
+    | UseViewModelInstanceFileParams
+    | UseViewModelInstanceViewModelParams
+    | UseViewModelInstanceRefParams
 ): ViewModelInstance | null {
-  const name = params?.name;
-  const useNew = params?.useNew ?? false;
+  const fileInstanceName = (params as { instanceName?: string } | undefined)
+    ?.instanceName;
+  const viewModelInstanceName = (params as { name?: string } | undefined)?.name;
+  const instanceName = fileInstanceName ?? viewModelInstanceName;
+  const artboardName = (params as UseViewModelInstanceFileParams | undefined)
+    ?.artboardName;
+  const viewModelName = (params as UseViewModelInstanceFileParams | undefined)
+    ?.viewModelName;
+  const useNew =
+    (params as UseViewModelInstanceViewModelParams | undefined)?.useNew ??
+    false;
   const required = params?.required ?? false;
   const onInit = params?.onInit;
 
@@ -152,13 +307,19 @@ export function useViewModelInstance(
   } | null>(null);
 
   const result = useMemo(() => {
-    const created = createInstance(source, name, useNew);
+    const created = createInstance(
+      source,
+      instanceName,
+      artboardName,
+      viewModelName,
+      useNew
+    );
     if (created.instance && onInit) {
       onInit(created.instance);
     }
     return created;
     // eslint-disable-next-line react-hooks/exhaustive-deps -- onInit excluded intentionally
-  }, [source, name, useNew]);
+  }, [source, instanceName, artboardName, viewModelName, useNew]);
 
   // Dispose previous instance if it changed and needed disposal
   if (
@@ -186,8 +347,10 @@ export function useViewModelInstance(
 
   if (required && result.instance === null) {
     throw new Error(
-      'useViewModelInstance: Failed to get ViewModelInstance. ' +
-        'Ensure the source has a valid ViewModel and instance available.'
+      result.error
+        ? `useViewModelInstance: ${result.error}`
+        : 'useViewModelInstance: Failed to get ViewModelInstance. ' +
+          'Ensure the source has a valid ViewModel and instance available.'
     );
   }
 

package/src/specs/RiveView.nitro.ts

@@ -25,7 +25,7 @@ export interface DataBindByName {
 export interface RiveViewProps extends HybridViewProps {
   /** Name of the artboard to display from the Rive file */
   artboardName?: string;
-  /** Name of the state mgachine to play */
+  /** Name of the state machine to play */
   stateMachineName?: string;
   /** Whether to automatically start playing the state machine */
   autoPlay?: boolean;