Hooks API Reference

This page provides a detailed reference for all the hooks exported by rive-react.

useRive

The primary hook for creating and managing a Rive instance.

Signature: 

function useRive(
  params?: UseRiveParameters,
  options?: Partial<UseRiveOptions>
): RiveState;

  • params: UseRiveParameters - An object containing properties to configure the Rive instance, such as src, artboard, animations, stateMachines, layout, and autoplay.
  • options: UseRiveOptions - An object for hook-specific configurations like useDevicePixelRatio and shouldResizeCanvasToContainer.
  • Returns: RiveState - An object containing the RiveComponent, rive instance, and refs.

useRiveFile

Hook for managing a RiveFile instance, useful for when you want to decouple file loading from rendering.

Signature: 

function useRiveFile(params: UseRiveFileParameters): RiveFileState;

  • params: UseRiveFileParameters - An object specifying the file source (src or buffer).
  • Returns: RiveFileState - An object with the riveFile instance and a status string.

useStateMachineInput

Hook to get a state machine input instance by name.

Signature: 

function useStateMachineInput(
  rive: Rive | null,
  stateMachineName?: string,
  inputName?: string,
  initialValue?: number | boolean
): StateMachineInput | null;

  • Returns: The StateMachineInput instance (SMIBoolean, SMINumber, or SMITrigger) or null.

useViewModel

Hook to retrieve a ViewModel definition from a Rive instance.

Signature: 

function useViewModel(
  rive: Rive | null,
  params?: UseViewModelParameters
): ViewModel | null;

  • params: { name: string } or { useDefault: true }.
  • Returns: The ViewModel definition or null.

useViewModelInstance

Hook to get a ViewModelInstance from a ViewModel.

Signature: 

function useViewModelInstance(
  viewModel: ViewModel | null,
  params?: UseViewModelInstanceParameters
): ViewModelInstance | null;

  • params: { name: string }, { useDefault: true }, or { useNew: true }. Can also include rive to auto-bind.
  • Returns: The ViewModelInstance or null.

Data Binding Property Hooks

These hooks are used to interact with properties on a ViewModelInstance.

  • useViewModelInstanceString(path, instance): Returns { value: string, setValue }.
  • useViewModelInstanceNumber(path, instance): Returns { value: number, setValue }.
  • useViewModelInstanceBoolean(path, instance): Returns { value: boolean, setValue }.
  • useViewModelInstanceColor(path, instance): Returns { value: number, setValue, setRgb, ... }.
  • useViewModelInstanceEnum(path, instance): Returns { value: string, values: string[], setValue }.
  • useViewModelInstanceTrigger(path, instance, params?): Returns { trigger }. Can accept an onTrigger callback in params.
  • useViewModelInstanceImage(path, instance): Returns { setValue }.
  • useViewModelInstanceList(path, instance): Returns { length, addInstance, removeInstanceAt, ... }.
  • useViewModelInstanceArtboard(path, instance): Returns { setValue }.

Utility Hooks

  • useResizeCanvas(...): Manages canvas resizing logic.
  • useDevicePixelRatio(...): Returns the current device pixel ratio.
  • useIntersectionObserver(): Provides observe and unobserve functions for tracking element visibility.