feat: add useViewModelInstanceImage hook

Author: damzobridge

examples/public/image_db_test.riv

@@ -2,7 +2,7 @@ import React, { useEffect } from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import { within, expect, waitFor, userEvent } from '@storybook/test';
 
-import { StringPropertyTest, NumberPropertyTest, BooleanPropertyTest, ColorPropertyTest, EnumPropertyTest, NestedViewModelTest, TriggerPropertyTest, PersonForm, PersonInstances } from './DataBindingTests';
+import { StringPropertyTest, NumberPropertyTest, BooleanPropertyTest, ColorPropertyTest, EnumPropertyTest, NestedViewModelTest, TriggerPropertyTest, PersonForm, PersonInstances, ImagePropertyTest } from './DataBindingTests';
 
 const meta: Meta = {
     title: 'Tests/DataBinding',
@@ -345,4 +345,44 @@ export const PersonFormStory: StoryObj = {
 };
 
 
+export const ImagePropertyStory: StoryObj = {
+    name: 'Image Property',
+    render: () => <ImagePropertyTest src="image_db_test.riv" />,
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+
+        // Wait for the Rive file to load
+        await waitFor(() => {
+            expect(canvas.getByTestId('load-random-image')).toBeTruthy();
+            expect(canvas.getByTestId('clear-image')).toBeTruthy();
+        }, { timeout: 3000 });
+
+        const loadImageButton = canvas.getByTestId('load-random-image');
+        const clearImageButton = canvas.getByTestId('clear-image');
+
+        expect(canvas.queryByTestId('current-image-url')).toBeNull();
+
+        // Load a random image
+        await userEvent.click(loadImageButton);
 
+        // Wait for the image to load and URL to appear
+        await waitFor(() => {
+            expect(canvas.getByTestId('current-image-url')).toBeTruthy();
+        }, { timeout: 5000 });
+
+        // Verify the image URL is displayed
+        const imageUrlElement = canvas.getByTestId('current-image-url');
+        expect(imageUrlElement.textContent).toContain('Current image: https://picsum.photos');
+
+        // Clear the image
+        await userEvent.click(clearImageButton);
+
+        // Load another image to test it works multiple times
+        await userEvent.click(loadImageButton);
+
+        // Wait for the new image to load
+        await waitFor(() => {
+            expect(canvas.getByTestId('current-image-url')).toBeTruthy();
+        }, { timeout: 5000 });
+    }
+};

examples/src/components/DataBindingTests.stories.tsx

@@ -9,7 +9,9 @@ import Rive, {
     useViewModelInstanceNumber,
     useViewModelInstanceEnum,
     useViewModelInstanceColor,
-    useViewModelInstanceTrigger
+    useViewModelInstanceTrigger,
+    useViewModelInstanceImage,
+    decodeImage
 } from '@rive-app/react-webgl2';
 
 
@@ -522,3 +524,90 @@ export const PersonInstances = ({ src }: { src: string }) => {
         </div>
     );
 };
+
+export const ImagePropertyTest = ({ src }: { src: string }) => {
+    const [currentImageUrl, setCurrentImageUrl] = useState<string>('');
+    const [isLoading, setIsLoading] = useState<boolean>(false);
+
+    const { rive, RiveComponent } = useRive({
+        src,
+        artboard: "Artboard",
+        stateMachines: "State Machine 1",
+        autoplay: true,
+        autoBind: false,
+    });
+
+    const viewModel = useViewModel(rive, { name: 'Post' });
+    const viewModelInstance = useViewModelInstance(viewModel, { rive });
+
+    const { setValue: setImage } = useViewModelInstanceImage(
+        'image',
+        viewModelInstance
+    );
+
+    const loadRandomImage = async () => {
+        if (!setImage) return;
+
+        setIsLoading(true);
+        try {
+            const imageUrl = `https://picsum.photos/400/300?random=${Date.now()}`;
+            setCurrentImageUrl(imageUrl);
+
+            const response = await fetch(imageUrl);
+            const imageBuffer = await response.arrayBuffer();
+            const decodedImage = await decodeImage(new Uint8Array(imageBuffer));
+
+            setImage(decodedImage);
+
+            decodedImage.unref();
+        } catch (error) {
+            console.error('Failed to load image:', error);
+        } finally {
+            setIsLoading(false);
+        }
+    };
+
+    const clearImage = () => {
+        if (setImage) {
+            setImage(null);
+            setCurrentImageUrl('');
+        }
+    };
+
+
+    return (
+        <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '20px' }}>
+            <div style={{ width: '400px', height: '300px', border: '1px solid #ccc' }}>
+                <RiveComponent />
+            </div>
+
+            {rive === null ? (
+                <div data-testid="loading-text">Loading…</div>
+            ) : (
+                <div style={{ display: 'flex', gap: '10px', alignItems: 'center' }}>
+                    <button
+                        onClick={loadRandomImage}
+                        disabled={isLoading}
+                        data-testid="load-random-image"
+                    >
+                        {isLoading ? 'Loading...' : 'Load Random Image'}
+                    </button>
+
+                    <button
+                        onClick={clearImage}
+                        disabled={isLoading}
+                        data-testid="clear-image"
+                    >
+                        Clear Image
+                    </button>
+                </div>
+            )}
+
+            {currentImageUrl && (
+                <div style={{ fontSize: '12px', color: '#666' }}>
+                    <span data-testid="current-image-url">Current image: {currentImageUrl}</span>
+                </div>
+            )}
+        </div>
+    );
+};

examples/src/components/DataBindingTests.tsx

@@ -0,0 +1,35 @@
+import { useCallback } from 'react';
+import { ViewModelInstance, ViewModelInstanceAssetImage } from '@rive-app/canvas';
+import { UseViewModelInstanceImageResult, RiveRenderImage } from '../types';
+import { useViewModelInstanceProperty } from './useViewModelInstanceProperty';
+
+/**
+ * Hook for interacting with image properties of a ViewModelInstance.
+ *
+ * @param path - Path to the image property (e.g. "profileImage" or "group/avatar")
+ * @param viewModelInstance - The ViewModelInstance containing the image property
+ * @returns An object with a setter function
+ */
+export default function useViewModelInstanceImage(
+    path: string,
+    viewModelInstance?: ViewModelInstance | null
+): UseViewModelInstanceImageResult {
+    const result = useViewModelInstanceProperty<ViewModelInstanceAssetImage, undefined, UseViewModelInstanceImageResult>(
+        path,
+        viewModelInstance,
+        {
+            getProperty: useCallback((vm, p) => vm.image(p), []),
+            getValue: useCallback(() => undefined, []), // Images don't have a readable value
+            defaultValue: null,
+            buildPropertyOperations: useCallback((safePropertyAccess) => ({
+                setValue: (newValue: RiveRenderImage | null) => {
+                    safePropertyAccess(prop => { prop.value = newValue; });
+                }
+            }), [])
+        }
+    );
+
+    return {
+        setValue: result.setValue
+    };
+}

src/hooks/useViewModelInstanceImage.ts

@@ -9,6 +9,7 @@ import useViewModelInstanceBoolean from './hooks/useViewModelInstanceBoolean';
 import useViewModelInstanceColor from './hooks/useViewModelInstanceColor';
 import useViewModelInstanceEnum from './hooks/useViewModelInstanceEnum';
 import useViewModelInstanceTrigger from './hooks/useViewModelInstanceTrigger';
+import useViewModelInstanceImage from './hooks/useViewModelInstanceImage';
 import useResizeCanvas from './hooks/useResizeCanvas';
 import useRiveFile from './hooks/useRiveFile';
 
@@ -26,6 +27,7 @@ export {
     useViewModelInstanceColor,
     useViewModelInstanceEnum,
     useViewModelInstanceTrigger,
+    useViewModelInstanceImage,
     RiveProps,
 };
 export {

src/index.ts

@@ -1,4 +1,5 @@
 import {
+  type decodeImage,
   Rive,
   RiveFile,
   RiveFileParameters,
@@ -185,4 +186,14 @@ export type UseViewModelInstanceTriggerResult = {
    * Fires the property trigger.
    */
   trigger: () => void;
+};
+
+export type RiveRenderImage = Awaited<ReturnType<typeof decodeImage>>;
+
+export type UseViewModelInstanceImageResult = {
+  /**
+   * Set the value of the image.
+   * @param value - The image to set.
+   */
+  setValue: (value: RiveRenderImage | null) => void;
 };