Working with ViewModel Properties

Once you have a ViewModelInstance, you can interact with its properties using a dedicated hook for each data type. These hooks simplify state synchronization between your React component and the Rive animation.

Note: All property hooks require the path to the property and the viewModelInstance it belongs to.

String Properties

Use useViewModelInstanceString to manage text values.

• Returns: { value: string | null, setValue: (v: string) => void }

import { useViewModelInstanceString } from '@rive-app/react-webgl2';

const { value: title, setValue: setTitle } = useViewModelInstanceString(
  'title',
  viewModelInstance
);

useEffect(() => {
  if (setTitle) {
    setTitle('My Awesome Dashboard');
  }
}, [setTitle]);

Number Properties

Use useViewModelInstanceNumber to manage numerical values.

• Returns: { value: number | null, setValue: (v: number) => void }

import { useViewModelInstanceNumber } from '@rive-app/react-webgl2';

const { value: stockChange, setValue: setStockChange } = useViewModelInstanceNumber(
  'apple/stockChange',
  viewModelInstance
);

useEffect(() => {
  if (setStockChange) {
    setStockChange(42.5);
  }
}, [setStockChange]);

Boolean Properties

Use useViewModelInstanceBoolean for true/false values.

• Returns: { value: boolean | null, setValue: (v: boolean) => void }

import { useViewModelInstanceBoolean } from '@rive-app/react-webgl2';

const { value: agreed, setValue: setAgreed } = useViewModelInstanceBoolean(
  'agreedToTerms',
  viewModelInstance
);

Color Properties

Use useViewModelInstanceColor for colors. It provides multiple ways to set the color.

• Returns: { value: number | null, setValue, setRgb, setRgba, ... }

import { useViewModelInstanceColor } from '@rive-app/react-webgl2';

const { value: color, setRgb } = useViewModelInstanceColor(
  'rootColor',
  viewModelInstance
);

const makeRed = () => setRgb(255, 0, 0);

Enum Properties

Use useViewModelInstanceEnum for properties with a predefined set of string values.

• Returns: { value: string | null, values: string[], setValue: (v: string) => void }

import { useViewModelInstanceEnum } from '@rive-app/react-webgl2';

const { value: shape, setValue: setShape, values: availableShapes } = useViewModelInstanceEnum(
  'logoShape',
  viewModelInstance
);
// availableShapes will be ['circle', 'square', 'triangle']

Trigger Properties

Use useViewModelInstanceTrigger to fire triggers.

• Returns: { trigger: () => void }

import { useViewModelInstanceTrigger } from '@rive-app/react-webgl2';

const { trigger: spinLogo } = useViewModelInstanceTrigger(
  'triggerSpinLogo',
  viewModelInstance
);

const onButtonClick = () => spinLogo();

You can also provide an onTrigger callback to the hook to execute code when the trigger is fired from within the Rive animation itself.

Image Properties

Use useViewModelInstanceImage to dynamically set images.

• Returns: { setValue: (img: RiveRenderImage | null) => void }

import { useViewModelInstanceImage, decodeImage } from '@rive-app/react-webgl2';

const { setValue: setImage } = useViewModelInstanceImage('image', viewModelInstance);

const loadNewImage = async () => {
  const response = await fetch('https://picsum.photos/400/300');
  const imageBuffer = await response.arrayBuffer();
  const decodedImage = await decodeImage(new Uint8Array(imageBuffer));
  setImage(decodedImage);
  decodedImage.unref(); // Release memory when done
}

List Properties

Use useViewModelInstanceList to manage lists of ViewModelInstances.

• Returns: An object with methods like length, addInstance, removeInstanceAt, getInstanceAt, swap.

import { useViewModelInstanceList } from '@rive-app/react-webgl2';

const { length, addInstance, getInstanceAt } = useViewModelInstanceList('items', viewModelInstance);

// Render a component for each item in the list
return (
  <div>
    {Array.from({ length }, (_, index) => (
      <TodoItemComponent key={index} todoItem={getInstanceAt(index)} />
    ))}
  </div>
);

Artboard Properties

Use useViewModelInstanceArtboard to dynamically set nested artboards.

• Returns: { setValue: (artboard: RiveArtboard | null) => void }

import { useViewModelInstanceArtboard } from '@rive-app/react-webgl2';

const { setValue: setArtboard1 } = useViewModelInstanceArtboard('artboard_1', viewModelInstance);

const handleSetArtboard = () => {
  if (rive) {
    const artboard = rive.getArtboard('ArtboardBlue');
    setArtboard1(artboard);
  }
};