feat: add useViewModelInstance hook with RiveFile support

Author: mfazekas

example/src/pages/MenuListExample.tsx

@@ -7,14 +7,15 @@ import {
   TextInput,
   ScrollView,
 } from 'react-native';
-import { useMemo, useRef } from 'react';
+import { useRef, useMemo } from 'react';
 import {
   Fit,
   RiveView,
   type ViewModelInstance,
   type RiveFile,
   useRiveFile,
   useRiveList,
+  useViewModelInstance,
 } from '@rive-app/react-native';
 import { type Metadata } from '../helpers/metadata';
 
@@ -37,18 +38,12 @@ export default function MenuListExample() {
 }
 
 function WithViewModelSetup({ file }: { file: RiveFile }) {
-  const viewModel = useMemo(() => file.viewModelByName('main'), [file]);
-  const instance = useMemo(
-    () => viewModel?.createDefaultInstance(),
-    [viewModel]
-  );
+  const instance = useViewModelInstance(file, { viewModelName: 'main' });
 
-  if (!instance || !viewModel) {
+  if (!instance) {
     return (
       <Text style={styles.errorText}>
-        {!viewModel
-          ? "No view model 'main' found"
-          : 'Failed to create view model instance'}
+        Failed to create view model instance for 'main'
       </Text>
     );
   }

src/hooks/useViewModelInstance.ts

@@ -0,0 +1,117 @@
+import { useState, useEffect, useMemo } from 'react';
+import type { ViewModel, ViewModelInstance } from '../specs/ViewModel.nitro';
+import type { RiveFile } from '../specs/RiveFile.nitro';
+
+export interface UseViewModelInstanceParams {
+  /**
+   * The name of the ViewModel to get from the RiveFile.
+   * Only used when passing a RiveFile as the first argument.
+   */
+  viewModelName?: string;
+  /**
+   * Get a specifically named instance from the ViewModel.
+   */
+  name?: string;
+  /**
+   * Get the default instance from the ViewModel.
+   * @default true
+   */
+  useDefault?: boolean;
+  /**
+   * Create a new (blank) instance from the ViewModel.
+   */
+  useNew?: boolean;
+}
+
+type ViewModelSource = ViewModel | RiveFile | null | undefined;
+
+function isRiveFile(source: ViewModelSource): source is RiveFile {
+  return source !== null && source !== undefined && 'viewModelByName' in source;
+}
+
+/**
+ * Hook for getting a ViewModelInstance from a ViewModel or RiveFile.
+ *
+ * Resolution order:
+ * 1. If `name` is provided, gets instance by name
+ * 2. If `useNew` is true, creates a new instance
+ * 3. Otherwise, gets the default instance
+ *
+ * @param source - The ViewModel or RiveFile to get an instance from
+ * @param params - Configuration for which instance to retrieve
+ * @returns The ViewModelInstance or null if not found
+ *
+ * @example
+ * ```tsx
+ * // From RiveFile (recommended)
+ * const instance = useViewModelInstance(riveFile, { viewModelName: 'main' });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // From ViewModel
+ * const viewModel = file.viewModelByName('main');
+ * const instance = useViewModelInstance(viewModel);
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Create a new blank instance
+ * const instance = useViewModelInstance(riveFile, {
+ *   viewModelName: 'TodoItem',
+ *   useNew: true
+ * });
+ * ```
+ */
+export function useViewModelInstance(
+  source: ViewModelSource,
+  params?: UseViewModelInstanceParams
+): ViewModelInstance | null {
+  const [instance, setInstance] = useState<ViewModelInstance | null>(null);
+
+  const viewModelName = params?.viewModelName;
+  const name = params?.name;
+  const useDefault = params?.useDefault ?? true;
+  const useNew = params?.useNew ?? false;
+
+  const viewModel = useMemo(() => {
+    if (!source) return null;
+    if (isRiveFile(source)) {
+      if (!viewModelName) {
+        console.warn(
+          'useViewModelInstance: viewModelName is required when passing a RiveFile'
+        );
+        return null;
+      }
+      return source.viewModelByName(viewModelName) ?? null;
+    }
+    return source;
+  }, [source, viewModelName]);
+
+  useEffect(() => {
+    if (!viewModel) {
+      setInstance(null);
+      return;
+    }
+
+    let vmi: ViewModelInstance | undefined;
+
+    if (name) {
+      vmi = viewModel.createInstanceByName(name);
+    } else if (useNew) {
+      vmi = viewModel.createInstance();
+    } else if (useDefault) {
+      vmi = viewModel.createDefaultInstance();
+    }
+
+    setInstance(vmi ?? null);
+
+    return () => {
+      if (vmi) {
+        vmi.dispose();
+      }
+    };
+  }, [viewModel, name, useDefault, useNew]);
+
+  return instance;
+}

src/index.tsx

@@ -49,6 +49,7 @@ 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 { useRiveFile } from './hooks/useRiveFile';
 export { type RiveFileInput } from './hooks/useRiveFile';
 export { DataBindMode };