repository·main·Indexed 22 days ago
https://github.com/rive-app/rive-reactA React wrapper for the rive-js/Wasm runtime that provides components and hooks for rendering interactive, stateful animations. It includes the Rive component for rendering assets, hooks for state machine and ViewModel control (such as useRive and useViewModelInstance), and specialized packages like @rive-app/react-canvas and @rive-app/react-canvas-lite for different bundle size and feature requirements. Compatible with React versions ^16.8.0 through ^19.0.0.
@rive-app/react-canvas package provides a React wrapper for Rive animations, utilizing the @rive-app/canvas JavaScript runtime. It is designed to integrate Rive's high-performance canvas rendering directly into React applications.The @rive-app/react-canvas-lite package is a lightweight version of the standard @rive-app/react-canvas package. It uses the @rive-app/canvas-lite JS runtime and shares the same API as the standard version.
Use this version when you need to minimize your application's bundle size. However, be aware of the following functional limitations:
Note that even if your Rive file contains Text or Audio components, using the Lite version will not cause application errors or prevent the rest of the graphic from rendering.
To integrate Rive React into your application, follow the official quickstart guides and API documentation provided by Rive:
For specific runtime features, refer to the following documentation topics:
The package provides several hooks to interact with the Rive runtime instance, manage state machines, and manipulate ViewModels.
Key hooks include:
useRive: Provides access to the Rive instance.useStateMachineInput: Allows you to control specific inputs within a state machine.useRiveFile: Manages loading Rive files.useResizeCanvas: Handles canvas resizing logic.ViewModel hooks allow for fine-grained control over specific data types within a ViewModel instance, such as useViewModelInstanceNumber, useViewModelInstanceString, useViewModelInstanceBoolean, etc.
import { useRive, useStateMachineInput } from '@rive-app/react-canvas';
function MyAnimation() {
const { rive } = useRive();
const input = useStateMachineInput(rive, 'State Machine 1', 'Input Name');
// Use input to control the animation
return null;
}Rive React is compatible with the following React versions:
^16.8.0 through ^19.0.0The Rive component is the primary way to render Rive animations in a React application. It accepts a src prop pointing to a Rive asset and allows you to configure artboards, animations, state machines, and layout settings. It also accepts standard HTML canvas attributes via spread props.
import Rive from '@rive-app/react-canvas';
function MyAnimation() {
return (
<Rive
src="path/to/your/asset.riv"
animations={["idle", "walk"]}
stateMachines={["State Machine 1"]}
shouldResizeCanvasToContainer
/>
);
}The useViewModel hook allows you to retrieve a specific ViewModel from a Rive instance.
Parameters:
name: (string) The name of the ViewModel to retrieve.useDefault: (boolean) If true, uses the default ViewModel from the Rive instance. Cannot be used if name is provided.The useViewModelInstanceProperty hook is a base utility for interacting with properties on a Rive ViewModelInstance. It manages the lifecycle of property access, keeps React state in sync with property changes, and provides a mechanism for safe property operations (like setting values or triggering events) even during hot-reloading.
To use this hook, you must provide a path to the property, the viewModelInstance, and an options object that defines how to interact with that specific property type.
import { useViewModelInstanceProperty } from 'rive-react';
// Note: Implementation requires providing specific logic for your property type
const { value, setValue, trigger } = useViewModelInstanceProperty(
'myPropertyPath',
viewModelInstance,
{
getProperty: (vm, path) => vm.getProperty(path),
getValue: (prop) => prop.value,
defaultValue: null,
buildPropertyOperations: (safeAccess) => ({
setValue: (newValue) => safeAccess((prop) => prop.value = newValue),
trigger: () => safeAccess((prop) => prop.trigger()),
}),
}
);Rive React provides a suite of hooks to interact with ViewModels and their specific instance types. This allows you to read or write data to the Rive runtime using strongly typed hooks:
useViewModel: Access the ViewModel.useViewModelInstance: Access a specific ViewModel instance.useGlobalViewModelInstance: Access a global ViewModel instance.For specific data types, use the corresponding instance hooks:
useViewModelInstanceNumberuseViewModelInstanceStringuseViewModelInstanceBooleanuseViewModelInstanceColoruseViewModelInstanceEnumuseViewModelInstanceTriggeruseViewModelInstanceImageuseViewModelInstanceListuseViewModelInstanceArtboardThe useGlobalViewModelInstance hook is used to manage a global ViewModel instance.
Parameters:
instanceName: (string) Resolve the view model instance with this name.useNew: (boolean) Create a new blank instance of the view model.instance: (ViewModelInstance | null) Register this caller-supplied instance directly.rive: (Rive | null) Registers the instance as the global and schedules a coalesced bind. Required for the hook to register/bind anything.The useViewModelInstance hook provides access to a specific instance within a ViewModel.
Parameters:
name: (string) The name of the instance to retrieve.useDefault: (boolean) Uses the default instance from the ViewModel.useNew: (boolean) Creates a new instance of the ViewModel.rive: (Rive | null) If provided, automatically binds the instance to this Rive instance.