React Native

Note that certain Rive features may not be supported yet for a particular runtime, or may require using the Rive Renderer.For more details, refer to the feature support and choosing a renderer pages.

@rive-app/react-native is the recommended Rive runtime for React Native. Built with Nitro, it replaces the legacy rive-react-native package.Starting with 0.5.0, it runs on Rive’s new native runtimes: the new Apple runtime on iOS, and on Android the runtime behind the new Compose API. If you’re upgrading from 0.4.x or from rive-react-native, see the migration guide.

Overview

This guide documents how to get started using the Rive React Native runtime. The source for the new runtime is available in its GitHub repository.

New Runtime (Recommended)
Legacy Runtime

Requirements

React Native: 0.78 or later (0.79+ recommended for improved Android error messages)
Expo SDK: 53 or later (for Expo users)
iOS: 15.1 or later
Android: SDK 24 (Android 7.0) or later
Xcode: 16.4 or later
JDK: 17 or later
Nitro Modules: 0.35.10 or later (0.36.2 or later on React Native 0.87+)

Quick Start

Follow these quick start steps to get familiar with the Rive React Native runtime.

Rive File

Remix/download the Rive file used in this quick start guide

Complete example

View the complete quick start example

Install the dependency

npm install @rive-app/react-native react-native-nitro-modules
# or for Yarn
yarn add @rive-app/react-native react-native-nitro-modules

react-native-nitro-modules is required as this library relies on Nitro Modules.

Setup

Import the necessary components and define styles for the following steps.

Imports

import {
  RiveView,
  useRive,
  useRiveFile,
  useRiveNumber,
  useRiveTrigger,
  useViewModelInstance,
  Fit,
} from '@rive-app/react-native';

Styles

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
  rive: {
    width: '100%',
    height: 400,
  },
});

Rive File and Component

The RiveView component displays Rive graphics. It requires a single prop: file, a RiveFile object.Use the useRiveFile hook to load a riv file and create a RiveFile object. This object can be cached and reused across multiple components.

Loading a file

export default function QuickStart() {
  const { riveFile } = useRiveFile(
    require('path/to/quick_start.riv')
  );

  return (
    <View style={styles.container}>
      {riveFile && <RiveView file={riveFile} style={styles.rive} />}
    </View>
  );
}

Further reading:

Props

Available view props for RiveView

Loading Rive Files

How to load Rive files in your app

Caching Rive Files

Cache Rive files for better performance

Layout

Configure how the graphic fits within its container.For this example, we’ll set fit to Layout, which automatically resizes the artboard to match the view size. This is ideal for responsive Rive graphics built with Layouts.

Layout

<RiveView
  file={riveFile}
  style={styles.rive}
  fit={Fit.Layout}
/>

Further reading:

Runtime layout

Control how Rive graphics fit and align within their containers

View Reference

Use the useRive() hook to access the Rive view reference for programmatic control.

useRive hook

export default function QuickStart() {
  const { riveFile } = useRiveFile(
    require('path/to/quick_start.riv')
  );
  const { riveViewRef, setHybridRef } = useRive();

  return (
    <View style={styles.container}>
      {riveFile && (
        <RiveView
          hybridRef={setHybridRef}
          file={riveFile}
          fit={Fit.Layout}
          style={styles.rive}
        />
      )}
    </View>
  );
}

Further reading:

View methods

See all the available view reference methods.

Hybrid Views

Read more on Nitro Hybrid Views.

Data binding

Create the view model instance manually using the useViewModelInstance hook and pass it to the view.This approach lets you set initial property values in the onInit callback before the view loads and decouples the ViewModelInstance from the RiveView.

Manually create view model instance

export default function QuickStart() {
  const { riveFile } = useRiveFile(
    require('path/to/quick_start.riv')
  );
  const { riveViewRef, setHybridRef } = useRive();
  const { instance: viewModelInstance, isLoading, error } = useViewModelInstance(riveFile, {
    async: true,
    onInit: (vmi) => vmi.numberProperty('health')!.set(20),
  });

  return (
    <View style={styles.container}>
      {riveFile && viewModelInstance && (
        <RiveView
          hybridRef={setHybridRef}
          file={riveFile}
          fit={Fit.Layout}
          style={styles.rive}
          dataBind={viewModelInstance}
        />
      )}
    </View>
  );
}

Use the view model property hooks to update and listen to property changes.

Property hooks

export default function QuickStart() {
  const { riveFile } = useRiveFile(
    require('path/to/quick_start.riv')
  );
  const { riveViewRef, setHybridRef } = useRive();
  const { instance: viewModelInstance, isLoading, error } = useViewModelInstance(riveFile, {
    async: true,
    onInit: (vmi) => vmi.numberProperty('health')!.set(20),
  });

  const { value: health, setValue: setHealth } = useRiveNumber(
    'health',
    viewModelInstance
  );

  console.log('health', health);

  const { trigger: gameOverTrigger } = useRiveTrigger(
    'gameOver',
    viewModelInstance,
    { onTrigger: () => console.log('Game Over Triggered') }
  );

  const handleTakeDamage = () => {
    setHealth((h) => (h ?? 0) - 7);
    riveViewRef!.playIfNeeded();
  };

  const handleMaxHealth = () => {
    setHealth(100);
    riveViewRef!.playIfNeeded();
  };

  const handleGameOver = () => {
    setHealth(0);
    gameOverTrigger();
    riveViewRef!.playIfNeeded();
  };

  return (
    <View style={styles.container}>
      {riveFile && viewModelInstance && (
        <RiveView
          hybridRef={setHybridRef}
          file={riveFile}
          fit={Fit.Layout}
          style={styles.rive}
          dataBind={viewModelInstance}
        />
      )}
      <Button onPress={handleTakeDamage} title="Take Damage" />
      <Button onPress={handleMaxHealth} title="Max Health" />
      <Button onPress={handleGameOver} title="Game Over" />
    </View>
  );
}

We call playIfNeeded to force the state machine to play. Under some circumstances, the state machine might be settled if there is no active timeline in the graphic.This is a temporary workaround. In the future, this will happen automatically.

Further reading:

Data binding

See the runtime data binding documentation for more information.

See our example app for more usage examples.

Key Components

`RiveView`

The component to render Rive content:

<RiveView
  file={riveFile}
/>

See the available props and methods.

`useRiveFile`

Hook for loading Rive files from a URL or local source:

const { riveFile } = useRiveFile(
  'https://cdn.rive.app/animations/vehicles.riv'
);
// or
// const { riveFile } = useRiveFile(require('./assets/graphic.riv'));

See loading Rive files and caching Rive files for more information.

`useRive`

Hook to access the Rive view reference for programmatic control:

const { riveViewRef, setHybridRef } = useRive();

<RiveView
  hybridRef={setHybridRef}
  file={riveFile}
/>

This is a Nitro Hybrid View. See the available view reference methods.

`useViewModelInstance`

Hook to create a view model instance from a RiveFile, ViewModel, or RiveViewRef.Pass async: true to create the instance asynchronously. The hook returns { instance, isLoading, error } and the instance is not available on the first render, so gate rendering on it. Without async: true, the instance is created through deprecated synchronous APIs that block the JS thread.

// From RiveFile — default artboard's ViewModel, default instance
const { instance, isLoading, error } = useViewModelInstance(riveFile, { async: true });

// From RiveFile — specify artboard or ViewModel name (mutually exclusive)
const { instance, isLoading, error } = useViewModelInstance(riveFile, { async: true, artboardName: 'MainArtboard' });
const { instance, isLoading, error } = useViewModelInstance(riveFile, { async: true, viewModelName: 'Settings' });

// instanceName can be combined with any of the above to pick a specific instance
const { instance, isLoading, error } = useViewModelInstance(riveFile, { async: true, instanceName: 'PersonInstance' });
const { instance, isLoading, error } = useViewModelInstance(riveFile, { async: true, viewModelName: 'Settings', instanceName: 'UserSettings' });

// From a ViewModel object
const { instance: namedInstance, isLoading, error } = useViewModelInstance(viewModel, { async: true, name: 'My Instance' });
const { instance: newInstance, isLoading, error } = useViewModelInstance(viewModel, { async: true, useNew: true });

// With required: true (throws once resolved to null, use with Error Boundary)
const { instance, isLoading, error } = useViewModelInstance(riveFile, { async: true, required: true });

// With onInit to set initial values before the instance is exposed or bound
const { instance, isLoading, error } = useViewModelInstance(riveFile, {
  async: true,
  onInit: (vmi) => {
    vmi.numberProperty('health')!.set(100);
  },
});

async: true is available in @rive-app/react-native@0.4.18 and later. The synchronous creation path is deprecated and will be removed in a future release.

Pass the dataBind prop in RiveView.

return (
  <RiveView
    file={riveFile}
    dataBind={instance}
  />
);

You can also get the auto-bound instance from a RiveViewRef — the hook waits for the view’s auto-bound instance to become available:

import { useRive, useViewModelInstance } from '@rive-app/react-native';

const { riveViewRef, setHybridRef } = useRive();
const { instance, isLoading, error } = useViewModelInstance(riveViewRef, { async: true });

See the runtime data binding documentation for more information.

Frame rate

By default, RiveView renders at the display’s refresh rate. Use the frameRate prop to cap it, for example to reduce the CPU and battery cost of a looping animation that doesn’t need 120 Hz:

// Cap rendering at 30 frames per second
<RiveView file={riveFile} frameRate={30} />

// Let the system pick a rate between 30 and 60, ideally 60
<RiveView file={riveFile} frameRate={{ minimum: 30, maximum: 60, preferred: 60 }} />

A range maps to CAFrameRateRange on iOS. Android doesn’t support ranges, so it caps at preferred, or maximum if preferred isn’t set. Remove the prop to return to the display’s refresh rate.Capping limits how many frames are drawn, not animation speed: playback still advances by the real time elapsed between frames.

frameRate requires 0.5.0 or later.

Semantics

Rive views can expose semantics defined in the editor to VoiceOver on iOS. See Semantics for the available modes.

Troubleshooting

Android build fails on Windows (CMake long-path error)

On Windows, the Android build can fail with ninja: error: mkdir(CMakeFiles/rive.dir/...): No such file or directory because paths exceed the Windows MAX_PATH (260-character) limit. This is a known issue across React Native libraries that use CMake.To fix this, set the CMAKE_VERSION environment variable to a newer CMake version (e.g. 3.31.6) before building:

set CMAKE_VERSION=3.31.6

See the Reanimated docs on building on Windows for full setup instructions.

Resources

GitHub

NPM

Example App

The legacy runtime is still supported, but we recommend migrating to the new runtime for better performance and features.

This guide documents how to get started using the legacy React Native runtime library. The source is available in its GitHub repository. This library contains an API for React Native apps to easily integrate Rive assets.The minimum iOS target is 14.0

See our documentation to add Rive to an Expo app.

Getting Started

Follow the steps below for a quick start on integrating Rive into your React Native app.

Install the dependency

npm install rive-react-native
# or for Yarn
yarn add rive-react-native

iOS - Pod Install

cd inside the ios folder and run pod install (if deploying to iOS)

If you run into issues here, you may need to bump the ios deployment version target to at least 14.0. You can find this version in the Podfile of the ios/ folder.

Android - Set Kotlin Dependency Resolution

This step may be optional - however, if your Android setup in the React Native project does not have Kotlin v1.8.0+ set up, you may run into duplicate class issues when building the project. To mitigate these issues, as suggested by Kotlin docs, add the following to your dependencies in your application’s build.gradle file to deal with version alignment:

dependencies {
    implementation platform('org.jetbrains.kotlin:kotlin-bom:1.8.0')
    ...
}

Add the Rive component

import Rive from 'rive-react-native';

function App() {
  return <Rive
      url="https://public.rive.app/community/runtime-files/2195-4346-avatar-pack-use-case.riv"
      artboardName="Avatar 1"
      stateMachineName="avatar"
      style={{width: 400, height: 400}}
  />;
}

Runtimes

Integrations

React Native

Overview

Requirements

Quick Start

Rive File

Complete example

Props

Loading Rive Files

Caching Rive Files

Runtime layout

View methods

Hybrid Views

Data binding

Key Components

`RiveView`

`useRiveFile`

`useRive`

`useViewModelInstance`

Frame rate

Semantics

Troubleshooting

Android build fails on Windows (CMake long-path error)

Resources

GitHub

NPM

Example App

Getting Started

Resources

GitHub

Example App

​Overview

​Requirements

​Quick Start

Rive File

Complete example

Props

Loading Rive Files

Caching Rive Files

Runtime layout

View methods

Hybrid Views

Data binding

​Key Components

​RiveView

​useRiveFile

​useRive

​useViewModelInstance

​Frame rate

​Semantics

​Troubleshooting

​Android build fails on Windows (CMake long-path error)

​Resources

GitHub

NPM

Example App

​Getting Started

​Resources

GitHub

Example App

Overview

Requirements

Quick Start

Key Components

`RiveView`

`useRiveFile`

`useRive`

`useViewModelInstance`

Frame rate

Semantics

Troubleshooting

Android build fails on Windows (CMake long-path error)

Resources

Getting Started

Resources