Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PDF
✓ import PDF from 'react-native-pdf';
✗ const PDF = require('react-native-pdf');
The primary component is a default export. While CommonJS `require` might work in some setups, ESM `import` is the standard and recommended approach.
PDF source object
✓ const source = { uri: 'http://example.com/test.pdf', cache: true };
The `source` prop accepts an object with `uri`, `uri` as base64 string, `fileName`, or `require` (for local assets). Cache option is common.
StyleSheet
✓ import { StyleSheet } from 'react-native';
Standard React Native StyleSheet for component styling, often used to define dimensions for the PDF viewer.
This quickstart demonstrates how to import and render a PDF from a URL using the `PDF` component. It includes basic error handling, page change logging, and styling to make the viewer occupy most of the screen, showing common props like `enablePaging`, `page`, `scale`, and `fitPolicy`.
import React from 'react';
import { StyleSheet, View, Text, Dimensions } from 'react-native';
import PDF from 'react-native-pdf';
const MyPdfViewer = () => {
// Example source: a public PDF URL
const source = {
uri: 'https://www.africau.edu/images/default/sample.pdf',
cache: true,
};
// For a local file, you might use:
// const localSource = { uri: 'file:///data/user/0/com.yourpackage/files/my_document.pdf' };
// For an asset:
// const assetSource = require('./assets/document.pdf');
return (
<View style={styles.container}>
<Text style={styles.title}>Viewing a PDF Document</Text>
<PDF
source={source}
onLoadComplete={(numberOfPages, filePath) => {
console.log(`Number of pages: ${numberOfPages}`);
}}
onPageChanged={(page, numberOfPages) => {
console.log(`Current page: ${page} / ${numberOfPages}`);
}}
onError={(error) => {
console.log(error);
}}
onPressLink={(uri) => {
console.log(`Link pressed: ${uri}`);
}}
style={styles.pdf}
enablePaging={true} // Enable horizontal paging for multi-page PDFs
page={1}
scale={1.0}
minScale={0.5}
maxScale={3.0}
fitPolicy={0} // 0: width, 1: height, 2: both
/>
</View>
);
};
const styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'flex-start',
alignItems: 'center',
marginTop: 25,
},
title: {
fontSize: 20,
fontWeight: 'bold',
marginBottom: 10,
},
pdf: {
flex: 1,
width: Dimensions.get('window').width,
height: Dimensions.get('window').height - 100, // Adjust height to leave space for title
},
});
export default MyPdfViewer;
Debug
Known issues
breakingAndroid builds for older projects might break due to the removal of `jcenter()` repository in favor of `mavenCentral()` (or `maven {}`).fixEnsure your `android/build.gradle` and `android/app/build.gradle` files are updated to use `mavenCentral()` or `maven { url '...' }` for dependencies. Specifically, remove `jcenter()` from your `repositories` blocks. affects: >=6.5.0
gotchaThe package `react-native-blob-util` is a required peer and runtime dependency that must be explicitly installed alongside `react-native-pdf`. Failing to install it will lead to runtime errors or crashes related to file system operations.fixAlways install both packages: `npm install react-native-pdf react-native-blob-util` or `yarn add react-native-pdf react-native-blob-util`.
affects: >=6.4.0
gotchaExpo Go does not support `react-native-pdf`. To use this package within an Expo project, you must use a Custom Dev Client with the provided Expo Config Plugin.fixRefer to the official Expo documentation on 'Custom Dev Clients' and the `react-native-pdf` GitHub repository's 'Expo Config Plugin' example (e.g., `with-pdf`) for proper setup.
affects: *
gotchaFor React Native 0.59.0 and above on Android, specific `packagingOptions` must be added to your `android/app/build.gradle` to prevent issues with native libraries (`libc++_shared.so`, `libjsc.so`).fixAdd the recommended `packagingOptions` block to your `android { ... }` configuration in `android/app/build.gradle` as specified in the installation instructions. affects: >=0.59.0 (React Native)
breakingVersion 7.0.0 and 7.0.1 included updates for Android 16 KB Page Size support and upgrading Fabric Example to Latest React Native 0.81.0, which may imply breaking changes or require updates for projects using Fabric architecture with older React Native versions.fixReview your Fabric setup and React Native version compatibility. Ensure your project aligns with `react-native@0.81.0` or newer if utilizing Fabric with `react-native-pdf@7.x`.
affects: >=7.0.0
Errors
Common errors & fixes
java.lang.IllegalStateException: Tried to access a JS module before the React instance was fully set up
This error typically indicates that native modules are being accessed too early in the React Native lifecycle or that there's an issue with the native module linking/initialization.
fixEnsure `react-native-pdf` and `react-native-blob-util` are correctly linked (automatic for RN 0.60+ with `pod install`, manual for older RN versions). Rebuild your native project after installation. This particular issue was fixed in `v6.7.6`, so upgrading might resolve it.
Undefined symbol: _OBJC_CLASS_$_RCTPdfViewManager
This usually means the iOS native module for `react-native-pdf` is not correctly linked or compiled.
fixFor React Native 0.60 and above, navigate to your `ios/` directory and run `pod install`. For older RN versions, ensure `react-native link react-native-pdf` was executed. Clean your Xcode build folder and try rebuilding.
Error: unable to find or load PDF document
The `source` prop is invalid, the URI is incorrect, the file doesn't exist at the specified path, or there are network issues preventing download.
fixDouble-check the `uri` or `filePath` in your `source` prop for typos or incorrect paths. Ensure network connectivity for remote PDFs. For local files, verify permissions and that the file actually exists on the device storage.
Error: Invariant Violation: ViewPropTypes is deprecated and will be removed from React Native in a future release. Use Image.propTypes instead.
This error occurs in older versions of `react-native-pdf` or React Native when `ViewPropTypes` was directly imported from `react-native` instead of `deprecated-react-native-prop-types`.
fixUpgrade `react-native-pdf` to `v6.6.0` or higher, which includes a fix to migrate to `deprecated-react-native-prop-types`.
Android build error related to `pickFirst 'lib/x86/libc++_shared.so'` or similar shared library conflicts.
Missing or incorrect `packagingOptions` in your `android/app/build.gradle` file, leading to conflicts when bundling native libraries.
fixAdd the `packagingOptions` block exactly as specified in the `react-native-pdf` Android installation instructions to your `android { ... }` block in `android/app/build.gradle`. Audit
Dependencies
reactrequiredPeer dependency required by React Native.
react-nativerequiredPeer dependency required for any React Native component.
react-native-blob-utilrequiredRequired runtime dependency for file system access, blob support, and caching functionalities. Must be installed alongside react-native-pdf.