feat: add useViewModelInstance hook

Author: mfazekas

example/src/pages/MenuListExample.tsx

@@ -15,6 +15,7 @@ import {
   type RiveFile,
   useRiveFile,
   useRiveList,
+  useViewModelInstance,
 } from '@rive-app/react-native';
 import { type Metadata } from '../helpers/metadata';
 
@@ -38,10 +39,7 @@ 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(viewModel);
 
   if (!instance || !viewModel) {
     return (

src/hooks/useViewModelInstance.ts

@@ -0,0 +1,81 @@
+import { useState, useEffect } from 'react';
+import type { ViewModel, ViewModelInstance } from '../specs/ViewModel.nitro';
+
+export interface UseViewModelInstanceParams {
+  /**
+   * 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;
+}
+
+/**
+ * Hook for getting a ViewModelInstance from a ViewModel.
+ *
+ * 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 viewModel - The ViewModel to get an instance from
+ * @param params - Configuration for which instance to retrieve
+ * @returns The ViewModelInstance or null if not found
+ *
+ * @example
+ * ```tsx
+ * const viewModel = file.viewModelByName('main');
+ * const instance = useViewModelInstance(viewModel);
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Create a new blank instance
+ * const viewModel = file.viewModelByName('TodoItem');
+ * const newInstance = useViewModelInstance(viewModel, { useNew: true });
+ * ```
+ */
+export function useViewModelInstance(
+  viewModel: ViewModel | null | undefined,
+  params?: UseViewModelInstanceParams
+): ViewModelInstance | null {
+  const [instance, setInstance] = useState<ViewModelInstance | null>(null);
+
+  const name = params?.name;
+  const useDefault = params?.useDefault ?? true;
+  const useNew = params?.useNew ?? false;
+
+  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 };