React Native

React Native runtime for Rive.

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.

🚀 The new Rive React Native runtime is now available! Built with Nitro for improved performance and better React Native integration.

Get started:

• Migration guide
• GitHub
• NPM

Migration Timeline:

• Short term: Complete the new runtime, see Feature Support and Roadmap
• Medium term: Address major concerns in the legacy package while supporting migration
• Long term: Full migration to the new package

We’re actively gathering feedback to improve the new runtime. Please share your thoughts and report any issues you encounter.

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)

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.25.2 or later

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

1. 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.

2. 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,
     },
   });
   
3. 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

4. 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

5. 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.

6. 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 } = useViewModelInstance(riveFile, {
       onInit: (vmi) => (vmi.numberProperty('health')!.value = 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 } = useViewModelInstance(riveFile, {
       onInit: (vmi) => (vmi.numberProperty('health')!.value = 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:

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

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

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

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

// With required: true (throws if null, use with Error Boundary)
const { instance } = useViewModelInstance(riveFile, { required: true });

// With onInit to set initial values synchronously
const { instance } = useViewModelInstance(riveFile, {
  onInit: (vmi) => {
    vmi.numberProperty('health')!.value = 100;
  },
});

Pass the dataBind prop in RiveView.

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

You can also get the auto-bound instance from a RiveViewRef:

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

const { riveViewRef, setHybridRef } = useRive();
const { instance } = useViewModelInstance(riveViewRef);

See the runtime data binding documentation for more information.

Resources

GitHub

NPM

Example App

Legacy Runtime

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.

1. Install the dependency

   npm install rive-react-native
   # or for Yarn
   yarn add rive-react-native
   
2. 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.

3. 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')
       ...
   }
   
4. 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}}
     />;
   }
   

Resources

GitHub

Example App