rive-react-native

The Rive component provides a bridge to the native Rive runtime on iOS and Android. You can load animations using either a local resourceName (a filename without the .riv extension) or a remote url. Note that you cannot provide both simultaneously.

Basic usage:

import Rive from 'rive-react-native';

function App() {
  return <Rive resourceName="truck_v7" />;
}

Import the Rive component from rive-react-native to display animations within your React Native application.

import Rive from 'rive-react-native';

export default function App() {
  return (
    <View>
      <Rive />
    </View>
  );
}

You can control the animation imperatively by using a ref with the RiveRef type. This allows you to call methods like play() and pause() on the component instance.

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

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

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

  return (
    <View>
      <Rive
        resourceName="truck_v7"
        ref={riveRef}
      />

      <Button onPress={handlePlayPress} title="play" />
    </View>
  );
}

To run the provided example project, install the dependencies and start the Expo development server. You can then open the app in a development build, an Android emulator, an iOS simulator, or Expo Go.

npm install
npx expo start

The example/ folder contains a sample application demonstrating how to use the Rive component and useRef hook pattern. It covers setting Rive files via URL or local assets, displaying multiple artboards, and manipulating state machines via inputs.

To run the example:

1. Run yarn bootstrap in the root directory.
2. Navigate to the example folder: cd example.
3. Run the app using Expo: yarn expo run:android or yarn expo run:ios.

Note for iOS: You may need to run pod install (for the first time) or pod update RiveRuntime in the example/iOS folder to install or update the underlying Rive iOS runtime.

If you want to start developing from scratch without the existing example code, run the reset-project script. This moves the current starter code into an app-example directory and creates a clean, blank app directory.

npm run reset-project

Install the Rive React Native SDK using yarn. For iOS projects, you must also install the native dependencies using CocoaPods.

yarn add rive-react-native

# For iOS only
cd ios && pod install

Rive assets can be loaded using several source types defined by RiveAssetPropType. You can provide a source via FileHandlerOptions using one of the following:

• Require Source: A numeric ID from a require() call (e.g., require('./asset.riv')).
• URI Source: An object with a uri string.
• Packaged Source: An object containing a fileName and an optional path (required for Android assets).

// Using a required asset
<Rive asset={require('./my_animation.riv')} />

// Using a URI
<Rive asset={{ uri: 'https://example.com/animation.riv' }} />

// Using a packaged asset (Android)
<Rive asset={{ fileName: 'my_animation.riv', path: 'assets/animations' }} />

To override the Android Rive runtime version in a Vanilla React Native project, add the Rive_RiveRuntimeAndroidVersion property to your android/gradle.properties file.

Version Resolution Priority (Android):

1. android/gradle.properties (Rive_RiveRuntimeAndroidVersion)
2. package.json (runtimeVersions.android)

Warning: Custom versions may become incompatible when you update rive-react-native. Always verify defaults in new releases.

Rive_RiveRuntimeAndroidVersion=11.7.2

By default, the library uses versions specified in package.json. If you need to override the iOS Rive runtime version in a Vanilla React Native project, create or edit ios/Podfile.properties.json and set the RiveRuntimeIOSVersion key.

Version Resolution Priority (iOS):

1. ios/Podfile.properties.json (RiveRuntimeIOSVersion)
2. package.json (runtimeVersions.ios)

Warning: Custom versions may become incompatible when you update rive-react-native. Always verify defaults in new releases.

{
  "RiveRuntimeIOSVersion": "6.21.1"
}

For Expo projects, use config plugins within your app.config.ts to override the native SDK versions. This ensures the correct versions are applied during the prebuild process.

Use withPodfileProperties for iOS and withGradleProperties for Android.

import { ExpoConfig, ConfigContext } from 'expo/config';
import { withPodfileProperties } from '@expo/config-plugins';
import { withGradleProperties } from '@expo/config-plugins';

export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  plugins: [
    [
      withPodfileProperties,
      {
        RiveRuntimeIOSVersion: '6.21.1',
      },
    ],
    [
      withGradleProperties,
      {
        Rive_RiveRuntimeAndroidVersion: '11.7.2',
      },
    ],
  ],
});