Rive Ref Methods - Rive

New Runtime (Recommended)
Legacy Runtime

Once you have access to the Rive ref object (via useRive hook), there are a number of methods available to invoke for controlling your Rive graphic.

() => Promise<void>

Starts playing the Rive graphic.

() => Promise<void>

Pauses the Rive graphic.

() => Promise<void>

Resets the Rive graphic to its initial state.

Deprecated. In 0.5.0 and later, this method is not supported: it logs an error and does nothing. To restart a graphic, remount the RiveView (for example, by changing its key).

() => void

Low overhead function to ensure the Rive graphic is playing. Use after property value updates to ensure the graphic is updated.

() => Promise<boolean>

Waits for the Rive view to be ready. Resolves to true once the view is configured, or false if configuration failed. The riveViewRef returned by useRive is only set after this resolves.

(viewModelInstance: ViewModelInstance) => void

Binds a view model instance to the Rive view. See the Data Binding documentation for more details.

() => ViewModelInstance | undefined

Gets the currently bound view model instance from the Rive view. Returns the bound ViewModelInstance, or undefined if none is bound.To wait for the auto-bound instance in a component, prefer useViewModelInstance(riveViewRef, { async: true }).

(name: string, value: string, path?: string) => void

Sets the text run value on the Rive view.

Deprecated, and only supported in 0.4.x. In 0.5.0 and later, this method throws. Use data binding instead.

(name: string, path?: string) => string

Gets the text run value from the Rive view.

Deprecated, and only supported in 0.4.x. In 0.5.0 and later, this method throws. Use data binding instead.

(name: string, value: number, path?: string) => void

Sets a number state machine input on the Rive view.

Deprecated, and only supported in 0.4.x. In 0.5.0 and later, this method throws. Use data binding instead.

(name: string, path?: string) => number

Gets a number state machine input from the Rive view.

Deprecated, and only supported in 0.4.x. In 0.5.0 and later, this method throws. Use data binding instead.

(name: string, value: boolean, path?: string) => void

Sets a boolean state machine input on the Rive view.

Deprecated, and only supported in 0.4.x. In 0.5.0 and later, this method throws. Use data binding instead.

(name: string, path?: string) => boolean

Gets a boolean state machine input from the Rive view.

Deprecated, and only supported in 0.4.x. In 0.5.0 and later, this method throws. Use data binding instead.

(name: string, path?: string) => void

Triggers a trigger state machine input on the Rive view.

Deprecated, and only supported in 0.4.x. In 0.5.0 and later, this method throws. Use data binding instead.

(onEvent: (event: UnifiedRiveEvent) => void) => void

Adds an event listener to the Rive view.

Deprecated, and only supported in 0.4.x. In 0.5.0 and later, this method throws. Use data binding instead.

() => void

Removes all event listeners from the Rive view.

Deprecated, and only supported in 0.4.x. In 0.5.0 and later, this method throws. Use data binding instead.

Once you have access to the Rive ref object, there are a number of methods available to invoke for controlling animations and state machines.

.play()

A reference method that will play a singular animation or state machine. For an animation currently playing it is a no-op.Type: (animationName?: string, loop?: LoopMode, direction?: Direction, isStateMachine?: boolean) => void

animationName - Specifies which singular animation should be played. We highly recommend passing a value here
- Default: ""
loop - Specifies which LoopMode should be used for playing the animations.
- Default: LoopMode.Auto
direction - Specifies which Direction should be used for playing the animations.
- Default: Direction.Auto
isStateMachine - Specifies whether the passed in animationName is a state machine or just a linear animation.
- Default: false

Example:

import Rive, { RiveRef } from 'rive-react-native';

const resourceName = 'truck_v7'

function App() {
  const riveRef = React.useRef<RiveRef>(null);

  const handlePlay = () => { riveRef.current?.play() };

  return (
    <>
      <Rive ref={riveRef} resourceName={resourceName} autoplay={false} />
      <Button onPress={handlePlay} title="Play">
    </>
  );
}

.pause()

A reference method that will pause any playing animation/state machine. For the animations currently stopped/paused it is no-op.Type: () => voidExample:

import Rive, { RiveRef } from 'rive-react-native';

const resourceName = 'truck_v7'

function App() {
  const riveRef = React.useRef<RiveRef>(null);

  const handlePause = () => { riveRef.current?.pause() };

  return (
    <>
      <Rive ref={riveRef} resourceName={resourceName} />
      <Button onPress={handlePause} title="Pause">
    </>
  );
}

.stop()

A reference method that will stop an animation/state machine. For the animations currently stopped/paused it is no-op.Type: () => voidExample:

import Rive, { RiveRef } from 'rive-react-native';

const resourceName = 'truck_v7'

function App() {
  const riveRef = React.useRef<RiveRef>(null);

  const handleStop = () => { riveRef.current?.stop() };

  return (
    <>
      <Rive ref={riveRef} resourceName={resourceName} />
      <Button onPress={handleStop} title="Stop">
    </>
  );
}

.reset()

A reference method that will reset the whole artboard. It will play animationName or the first animation (if animationName hasn’t been passed) immediately if autoplay hasn’t been set to false explicitly.Type: () => void

import Rive, { RiveRef } from 'rive-react-native';

const resourceName = 'truck_v7'

function App() {
  const riveRef = React.useRef<RiveRef>(null);

  const handleReset = () => { riveRef.current?.reset() };

  return (
    <>
      <Rive ref={riveRef} resourceName={resourceName} autoplay={true} />
      <Button onPress={handleReset} title="Reset">
    </>
  );
}

.fireState()

A reference method that will fire trigger identified by the inputName on all active matching state machines.Type: (stateMachineName: string, inputName: string) => void

stateMachineName - Specifies state machine name which will be matched against all active state machines.
inputName - Specifies the name of the trigger that should be fired.

Example:

import Rive, { RiveRef } from 'rive-react-native';

const resourceName = 'ui_swipe_left_to_delete'

function App() {
  const riveRef = React.useRef<RiveRef>(null);

  const handleFireState = () => { riveRef.current?.fireState('Swipe to delete', 'Trigger Delete') };

  return (
    <>
      <Rive ref={riveRef} resourceName={resourceName} autoplay={true} />
      <Button onPress={handleFireState} title="FireState">
    </>
  );
}

.setInputState()

A reference method that will set input state identified by the inputName on all active matching state machines to the given value.Type: (stateMachineName: string, inputName: string, value: boolean | number) => void

stateMachineName - Specifies state machine name which will be matched against all active state machines.
inputName - Specifies name of the input which state should be updated.
value - Specifies a value that the input state should be set to.

Example:

import Rive, { RiveRef } from 'rive-react-native';

const resourceName = 'ui_swipe_left_to_delete'
const threshold = 50

function App() {
  const riveRef = React.useRef<RiveRef>(null);

  const handleFireState = () => {
    riveRef.current?.setInputState(
      'Swipe to delete',
      'Swipe Threshold',
      threshold
    );
  };

  return (
    <>
      <Rive ref={riveRef} resourceName={resourceName} autoplay={true} />
      <Button onPress={handleFireState} title="FireState">
    </>
  );
}

.setTextRunValue()

A reference method that will set a text run value (via value) on a given text run (via textRunName).Type: setTextRunValue: (textRunName: string, value: string) => void

textRunName - Name of the text run to set a new text value on. Read more on text runs here: Text
value - Specifies a new text value that should be set on the text run

Example:

import Rive, { RiveRef } from 'rive-react-native';

const resourceName = 'ui_swipe_left_to_delete'
const threshold = 50

function App() {
  const riveRef = React.useRef<RiveRef>(null);

  const handleSetText = () => {
    riveRef.current?.setTextRunValue(
      'MyRunName',
      'New Text',
    );
  };

  return (
    <>
      <Rive ref={riveRef} resourceName={resourceName} autoplay={true} />
      <Button onPress={handleSetText} title="SetText">
    </>
  );
}