docs(react-native): update useViewModelInstance API for viewModelName and instanceName params

Author: mfazekas

runtimes/data-binding.mdx

@@ -601,6 +601,27 @@ Once we have a reference to a view model, it can be used to create an instance.
         // Get default instance from RiveFile (recommended)
         const instance = useViewModelInstance(riveFile);
 
+        // Get a specific instance by name from the default artboard's ViewModel
+        const instance = useViewModelInstance(riveFile, { instanceName: 'PersonInstance' });
+
+        // Get the ViewModel assigned to a specific artboard
+        const instance = useViewModelInstance(riveFile, { artboardName: 'MainArtboard' });
+
+        // Get a specific instance from a specific artboard
+        const instance = useViewModelInstance(riveFile, {
+            artboardName: 'MainArtboard',
+            instanceName: 'SpecificInstance',
+        });
+
+        // Get a ViewModel by name (file-wide lookup)
+        const instance = useViewModelInstance(riveFile, { viewModelName: 'Settings' });
+
+        // Get a specific instance from a named ViewModel
+        const instance = useViewModelInstance(riveFile, {
+            viewModelName: 'Settings',
+            instanceName: 'UserSettings',
+        });
+
         // Get instance by name from a ViewModel
         const viewModel = riveFile?.viewModelByName('My View Model');
         const namedInstance = useViewModelInstance(viewModel, { name: 'My Instance' });
@@ -628,6 +649,13 @@ Once we have a reference to a view model, it can be used to create an instance.
         );
         ```
 
+        When using a `RiveFile` source, `artboardName` and `viewModelName` are mutually exclusive:
+        - No params: uses the default artboard's ViewModel and creates the default instance
+        - `artboardName`: gets the ViewModel assigned to that artboard
+        - `viewModelName`: looks up a ViewModel by name across the entire file
+
+        `instanceName` can be combined with any of the above. If provided, it creates a specific named instance via `createInstanceByName()`. Otherwise, the default instance is created.
+
         You can also get the auto-bound instance from a `RiveViewRef`:
 
         ```tsx

runtimes/react-native/react-native.mdx

@@ -379,19 +379,36 @@ This guide documents how to get started using the Rive React Native runtime. The
     // Get default instance from RiveFile (recommended)
     const instance = useViewModelInstance(riveFile);
 
-    // or
+    // Get a specific instance by name from the default artboard's ViewModel
+    const instance = useViewModelInstance(riveFile, { instanceName: 'PersonInstance' });
+
+    // Get the ViewModel assigned to a specific artboard
+    const instance = useViewModelInstance(riveFile, { artboardName: 'MainArtboard' });
+
+    // Get a specific instance from a specific artboard
+    const instance = useViewModelInstance(riveFile, {
+      artboardName: 'MainArtboard',
+      instanceName: 'SpecificInstance',
+    });
+
+    // Get a ViewModel by name (file-wide lookup)
+    const instance = useViewModelInstance(riveFile, { viewModelName: 'Settings' });
+
+    // Get a specific instance from a named ViewModel
+    const instance = useViewModelInstance(riveFile, {
+      viewModelName: 'Settings',
+      instanceName: 'UserSettings',
+    });
+
     // Get named instance from a ViewModel
     const namedInstance = useViewModelInstance(viewModel, { name: 'My Instance' });
 
-    // or
     // Create a new blank instance from a ViewModel
     const newInstance = useViewModelInstance(viewModel, { useNew: true });
 
-    // or
     // With required: true (throws if null, use with Error Boundary)
     const instance = useViewModelInstance(riveFile, { required: true });
 
-    // or
     // With onInit to set initial values synchronously
     const instance = useViewModelInstance(riveFile, {
       onInit: (vmi) => {
@@ -401,6 +418,13 @@ This guide documents how to get started using the Rive React Native runtime. The
     });
     ```
 
+    When using a `RiveFile` source, `artboardName` and `viewModelName` are mutually exclusive:
+    - No params: uses the default artboard's ViewModel and creates the default instance
+    - `artboardName`: gets the ViewModel assigned to that artboard
+    - `viewModelName`: looks up a ViewModel by name across the entire file
+
+    `instanceName` can be combined with any of the above. If provided, it creates a specific named instance via `createInstanceByName()`. Otherwise, the default instance is created.
+
     Pass the `dataBind` prop in `RiveView`.
     ```ts
     return (