feat: add useRiveList hook for list property management

Author: mfazekas

example/src/pages/DataBindingListExample.tsx

@@ -5,14 +5,15 @@ import {
   ActivityIndicator,
   TouchableOpacity,
 } from 'react-native';
-import { useMemo, useState, useCallback, useRef } from 'react';
+import { useMemo, useState, useRef } from 'react';
 import {
   Fit,
   RiveView,
   type ViewModelInstance,
   type RiveFile,
   type RiveViewRef,
   useRiveFile,
+  useRiveList,
 } from '@rive-app/react-native';
 import { type Metadata } from '../helpers/metadata';
 
@@ -65,18 +66,10 @@ function ListExample({
 }) {
   const riveRef = useRef<RiveViewRef>(null);
   const [isPlaying, setIsPlaying] = useState(true);
-  const listProperty = useMemo(
-    () => instance.listProperty('ListItemVM'),
-    [instance]
-  );
-  const [listLength, setListLength] = useState(listProperty?.length ?? 0);
-
-  const refreshLength = useCallback(() => {
-    setListLength(listProperty?.length ?? 0);
-  }, [listProperty]);
+  const { length, addInstance, removeInstanceAt, swap, getInstanceAt, error } =
+    useRiveList('ListItemVM', instance);
 
-  const handleAddItem = useCallback(() => {
-    if (!listProperty) return;
+  const handleAddItem = () => {
     const buttonVM = file.viewModelByName('button VM');
     if (!buttonVM) {
       console.error('button VM view model not found');
@@ -91,54 +84,47 @@ function ListExample({
     if (stringProp) {
       stringProp.value = 'new btn';
     }
-    listProperty.addInstance(newInstance);
+    addInstance(newInstance);
     riveRef.current?.playIfNeeded();
-    refreshLength();
-  }, [listProperty, file, refreshLength]);
+  };
 
-  const handleRemoveFirst = useCallback(() => {
-    if (!listProperty || listProperty.length === 0) return;
-    listProperty.removeInstanceAt(0);
+  const handleRemoveFirst = () => {
+    if (length === 0) return;
+    removeInstanceAt(0);
     riveRef.current?.playIfNeeded();
-    refreshLength();
-  }, [listProperty, refreshLength]);
+  };
 
-  const handleRemoveLast = useCallback(() => {
-    if (!listProperty || listProperty.length === 0) return;
-    listProperty.removeInstanceAt(listProperty.length - 1);
+  const handleRemoveLast = () => {
+    if (length === 0) return;
+    removeInstanceAt(length - 1);
     riveRef.current?.playIfNeeded();
-    refreshLength();
-  }, [listProperty, refreshLength]);
+  };
 
-  const handleSwapFirstTwo = useCallback(() => {
-    if (!listProperty || listProperty.length < 2) return;
-    listProperty.swap(0, 1);
+  const handleSwapFirstTwo = () => {
+    if (length < 2) return;
+    swap(0, 1);
     riveRef.current?.playIfNeeded();
-    refreshLength();
-  }, [listProperty, refreshLength]);
-
-  const logListItems = useCallback(() => {
-    if (!listProperty) return;
-    console.log(`List has ${listProperty.length} items:`);
-    for (let i = 0; i < listProperty.length; i++) {
-      const item = listProperty.getInstanceAt(i);
+  };
+
+  const logListItems = () => {
+    console.log(`List has ${length} items:`);
+    for (let i = 0; i < length; i++) {
+      const item = getInstanceAt(i);
       console.log(`  [${i}]: ${item?.instanceName ?? 'undefined'}`);
     }
-  }, [listProperty]);
+  };
 
-  const handlePlayPause = useCallback(() => {
+  const handlePlayPause = () => {
     if (isPlaying) {
       riveRef.current?.pause();
     } else {
       riveRef.current?.play();
     }
     setIsPlaying(!isPlaying);
-  }, [isPlaying]);
+  };
 
-  if (!listProperty) {
-    return (
-      <Text style={styles.errorText}>ListItemVM list property not found</Text>
-    );
+  if (error) {
+    return <Text style={styles.errorText}>{error.message}</Text>;
   }
 
   return (
@@ -156,7 +142,7 @@ function ListExample({
         file={file}
       />
       <View style={styles.controls}>
-        <Text style={styles.infoText}>List length: {listLength}</Text>
+        <Text style={styles.infoText}>List length: {length}</Text>
         <View style={styles.buttonRow}>
           <TouchableOpacity style={styles.button} onPress={handleAddItem}>
             <Text style={styles.buttonText}>Add Item</Text>

src/hooks/useRiveList.ts

@@ -0,0 +1,109 @@
+import { useCallback, useEffect, useState, useMemo } from 'react';
+import type { ViewModelInstance } from '../specs/ViewModel.nitro';
+import type { UseRiveListResult } from '../types';
+
+/**
+ * Hook for interacting with list ViewModel instance properties.
+ *
+ * @param path - The path to the list property
+ * @param viewModelInstance - The ViewModelInstance containing the list property
+ * @returns An object with list length, manipulation methods, and error state
+ */
+export function useRiveList(
+  path: string,
+  viewModelInstance?: ViewModelInstance | null
+): UseRiveListResult {
+  const [error, setError] = useState<Error | null>(null);
+  const [revision, setRevision] = useState(0);
+
+  useEffect(() => {
+    setError(null);
+  }, [path, viewModelInstance]);
+
+  const property = useMemo(() => {
+    if (!viewModelInstance) return undefined;
+    return viewModelInstance.listProperty(path);
+  }, [viewModelInstance, path]);
+
+  useEffect(() => {
+    if (viewModelInstance && !property) {
+      setError(
+        new Error(`List property "${path}" not found in the ViewModel instance`)
+      );
+    }
+  }, [viewModelInstance, property, path]);
+
+  useEffect(() => {
+    if (!property) return;
+
+    const removeListener = property.addListener(() => {
+      setRevision((r) => r + 1);
+    });
+
+    return () => {
+      removeListener();
+      property.removeListeners();
+      property.dispose();
+    };
+  }, [property]);
+
+  const length = useMemo(() => {
+    // revision is used to trigger re-computation when list changes
+
+    revision;
+    return property?.length ?? 0;
+  }, [property, revision]);
+
+  const getInstanceAt = useCallback(
+    (index: number) => {
+      return property?.getInstanceAt(index);
+    },
+    [property]
+  );
+
+  const addInstance = useCallback(
+    (instance: ViewModelInstance) => {
+      property?.addInstance(instance);
+    },
+    [property]
+  );
+
+  const addInstanceAt = useCallback(
+    (instance: ViewModelInstance, index: number) => {
+      return property?.addInstanceAt(instance, index) ?? false;
+    },
+    [property]
+  );
+
+  const removeInstance = useCallback(
+    (instance: ViewModelInstance) => {
+      property?.removeInstance(instance);
+    },
+    [property]
+  );
+
+  const removeInstanceAt = useCallback(
+    (index: number) => {
+      property?.removeInstanceAt(index);
+    },
+    [property]
+  );
+
+  const swap = useCallback(
+    (index1: number, index2: number) => {
+      return property?.swap(index1, index2) ?? false;
+    },
+    [property]
+  );
+
+  return {
+    length,
+    getInstanceAt,
+    addInstance,
+    addInstanceAt,
+    removeInstance,
+    removeInstanceAt,
+    swap,
+    error,
+  };
+}

src/index.tsx

@@ -48,6 +48,7 @@ export { useRiveBoolean } from './hooks/useRiveBoolean';
 export { useRiveEnum } from './hooks/useRiveEnum';
 export { useRiveColor } from './hooks/useRiveColor';
 export { useRiveTrigger } from './hooks/useRiveTrigger';
+export { useRiveList } from './hooks/useRiveList';
 export { useRiveFile } from './hooks/useRiveFile';
 export { type RiveFileInput } from './hooks/useRiveFile';
 export { DataBindMode };

src/types.tsx

@@ -32,3 +32,49 @@ export interface UseRiveTriggerResult {
 export type UseViewModelInstanceTriggerParameters = {
   onTrigger?: () => void;
 };
+
+export interface UseRiveListResult {
+  /**
+   * The number of instances in the list.
+   */
+  length: number;
+  /**
+   * Get the instance at the given index.
+   */
+  getInstanceAt: (
+    index: number
+  ) => import('./specs/ViewModel.nitro').ViewModelInstance | undefined;
+  /**
+   * Add an instance to the end of the list.
+   */
+  addInstance: (
+    instance: import('./specs/ViewModel.nitro').ViewModelInstance
+  ) => void;
+  /**
+   * Add an instance at the given index.
+   * @returns true if successful
+   */
+  addInstanceAt: (
+    instance: import('./specs/ViewModel.nitro').ViewModelInstance,
+    index: number
+  ) => boolean;
+  /**
+   * Remove an instance from the list.
+   */
+  removeInstance: (
+    instance: import('./specs/ViewModel.nitro').ViewModelInstance
+  ) => void;
+  /**
+   * Remove the instance at the given index.
+   */
+  removeInstanceAt: (index: number) => void;
+  /**
+   * Swap the instances at the given indices.
+   * @returns true if successful
+   */
+  swap: (index1: number, index2: number) => boolean;
+  /**
+   * The error if the property is not found.
+   */
+  error: Error | null;
+}