Rive React Native

Common errors

• Could not find com.rive-app:rive-android:<version> in any of the following locations:

  cause Android build failed to locate the Rive Android native library due to a dependency resolution issue, often after a package update or build cache corruption.
  fix Ensure your project-level `build.gradle` includes `mavenCentral()` in `allprojects { repositories { ... } }`. Then, clean your Android project by running `cd android && ./gradlew clean` and rebuild.

• RiveRuntime/RiveRuntime.h file not found

  cause iOS build failed to locate the Rive iOS native framework header, indicating a CocoaPods issue where the native module isn't correctly linked.
  fix Navigate to your `ios` project folder (`cd ios`) and run `pod install` or `pod update RiveRuntime`. Ensure your `Podfile` includes `use_native_modules!` and `pod 'RiveRuntime', :path => '../node_modules/rive-react-native'` (if manually linked).

• Failed to play animation: <animation name> - animation not found

  cause The specified animation name (via `animationName` prop or `play()` method) does not exist within the loaded Rive file or is misspelled.
  fix Verify the animation name exactly matches what is defined in your Rive file (case-sensitive). You can use `riveRef.current.getAnimationNames()` to inspect all available animation names at runtime.

• error: cannot find symbol class RiveReactNativePackage

  cause This error typically occurs on Android when the Rive React Native package isn't properly linked, especially after manual linking or issues with auto-linking.
  fix For React Native 0.60+, auto-linking should handle this. If it persists, try `npx react-native link rive-react-native`, ensure `new RiveReactNativePackage()` is present in your `MainApplication.java` (if linking manually or older RN), clean your Android build cache, and rebuild.

Warnings

• deprecated This package is a legacy runtime. The Rive team strongly recommends migrating to the new, performance-optimized `@rive-app/react-native` (Nitro runtime) for all new development and future-proofing. This package will eventually be superseded.
  Fix: Refer to the official Rive documentation and the `@rive-app/react-native` GitHub repository for migration guides and new runtime usage. Plan to transition your existing projects.
• breaking Frequent bumps to the underlying native Rive iOS and Android runtimes (e.g., Rive Android 11.4.0, iOS 6.18.2 in v9.8.2) may introduce subtle breaking changes, new requirements, or necessitate updates to native build configurations. Always review release notes for the specific native SDKs.
  Fix: Check the changelogs for `rive-android` and `rive-ios` linked in the `rive-react-native` release notes for each update. After upgrading, run `cd ios && pod update RiveRuntime` and perform a clean Android build (e.g., `cd android && ./gradlew clean && ./gradlew assembleDebug`).
• gotcha Minimum supported device versions are iOS 14.0+ and Android SDK 21+ with a target SDK 33+. Ensure your project's native configurations meet these minimums to avoid compatibility issues or build failures.
  Fix: Update your project's `Podfile` (iOS) to `platform :ios, '14.0'` and `build.gradle` (Android) to specify `minSdkVersion 21` and `targetSdkVersion 33` (or higher, as recommended by React Native).
• gotcha When using local Rive `.riv` assets, ensure the `resourceName` prop matches the filename (without extension) exactly. The assets must also be correctly bundled within your native project, which is a common source of 'file not found' errors.
  Fix: For iOS, drag `.riv` files into your Xcode project and ensure they are part of a target's 'Copy Bundle Resources'. For Android, place `.riv` files in `android/app/src/main/res/raw/`. For Expo managed workflow, follow Expo's asset bundling guidelines. Paths with subfolders can be tricky on iOS Release builds, verify your setup.

Install

• npm install rive-react-native npm
• yarn add rive-react-native yarn
• pnpm add rive-react-native pnpm

Imports

• Rive
  wrong:

  const Rive = require('rive-react-native').Rive;

  correct:

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

  The primary component for rendering Rive animations in your React Native app. It's a named export.
• useRive
  wrong:

  import useRive from 'rive-react-native';

  correct:

  import { useRive } from 'rive-react-native';

  A React hook for programmatic control over Rive animations and state machines. It's a named export.
• RiveRef
  wrong:

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

  correct:

  import type { RiveRef } from 'rive-react-native';

  This is a TypeScript type definition for the ref object used to control the Rive component programmatically. Import it as a type.

Quickstart

Demonstrates how to embed a Rive animation from a local asset (e.g., 'truck_delivery_loop.riv') in a React Native component, including basic autoplay, specifying artboards/animations, and interacting with the Rive component via a ref.

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

const RiveAnimationScreen: React.FC = () => {
  const riveRef = React.useRef<RiveRef>(null);

  // Example of how you might interact with the Rive component via its ref
  React.useEffect(() => {
    // For instance, activating a state machine input after 3 seconds
    const timer = setTimeout(() => {
      if (riveRef.current) {
        console.log('Activating input...');
        riveRef.current.fireState('Motion', 'Trigger1'); // Example: assumes a state machine 'Motion' with a trigger input 'Trigger1'
      }
    }, 3000);
    return () => clearTimeout(timer);
  }, []);

  return (
    <View style={styles.container}>
      <Text style={styles.header}>Loading Rive Animation</Text>
      <Rive
        ref={riveRef}
        resourceName="truck_delivery_loop" // Ensure 'truck_delivery_loop.riv' is in your native project's assets
        autoplay={true}
        artboardName="New Artboard" // Optional: specify a particular artboard
        animationName="Timeline 1" // Optional: specify a particular animation
        style={styles.riveAnimation}
        onLoad={() => console.log('Rive file loaded successfully!')}
        onError={(error) => console.error('Rive error:', error)}
      />
      <Text style={styles.footer}>Interactive Rive animation</Text>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#F5FCFF',
  },
  header: {
    fontSize: 20,
    marginBottom: 20,
  },
  riveAnimation: {
    width: 300,
    height: 300,
    backgroundColor: 'transparent',
  },
  footer: {
    marginTop: 20,
    fontSize: 16,
    color: '#666',
  },
});

export default RiveAnimationScreen;