How to build a React Native PDF viewer

This article was first published in June 2021 and was updated in November 2024.

Integrating a PDF viewer in a React Native app can enhance user experience by allowing easy document handling and display across iOS and Android platforms. This article will show you how to set up a PDF viewer using two different libraries: the open source react-native-pdf, and the commercial Nutrient React Native PDF SDK .

You’ll learn how to create a new project, add the necessary dependencies, configure platform-specific settings, and display a PDF document. By the end of this tutorial, you’ll have a fully functional PDF viewer in your React Native app.

Introduction to React Native PDF viewers

React Native PDF viewers are essential components for mobile applications that require displaying PDF files. These viewers enable users to interact with PDF documents directly within the app, providing a seamless user experience. With features like zooming, scrolling, and page navigation, React Native PDF viewers make it easy for users to navigate through PDF files. They support various PDF formats, including PDF 1.7 and later versions, ensuring compatibility with a wide range of documents. By integrating a native PDF viewer into your React Native project, you can enhance your app’s functionality and offer users a more comprehensive document handling experience.

Why add PDF support to your app?

Adding PDF support to your app enables it to handle various document needs, from basic viewing, to advanced functionalities like annotations, form filling, and digital signatures. Choosing the right library can help you implement features that are essential for your app’s success.

React Native PDF viewer use case

This post assumes you’re familiar with React Native and that you’ve previously developed apps using React Native. If that isn’t the case, you can use our getting started guides to create a new React Native project that uses Nutrient. Or, if you’re in a hurry, you can download our ready-to-run example project and follow the instructions from its README.

In the video below, you can see how we open a PDF file using react-native-pdf and Nutrient React Native SDK.

Now, let’s take a look at the steps involved!

Prerequisites

Before getting started, ensure you have the following:

• A development environment for React Native using the React Native CLI (not the Expo CLI)

• The latest stable versions of Android Studio, the Android NDK, and an Android Virtual Device or hardware device

• The latest stable versions of Xcode and CocoaPods

Step 1 — Creating a new React Native project

Open your terminal and navigate to the directory where you want to create your project. For this example, you’ll use the ~/Documents/ directory:

cd ~/Documents

Create a new React Native project:

npx react-native@latest init ReactNativePDFViewer

Next, you’ll add the required dependencies.

Step 2 — Installing the Nutrient dependency

1. Navigate to your project directory:

cd ReactNativePDFViewer

2. Then, add the Nutrient dependency:

yarn add react-native-pspdfkit@github:PSPDFKit/react-native

3. Install all the dependencies for the project:

yarn install

Step 3 — Configuring the Android platform

1. Open android/build.gradle and add the Nutrient repository:

allprojects {
    repositories {
        mavenCentral()
+       maven { url 'https://my.nutrient.io/maven/' }
    }
}

2. Open android/app/build.gradle and update the SDK versions:

android {
-   compileSdkVersion rootProject.ext.compileSdkVersion
+   compileSdkVersion 34

    defaultConfig {
        applicationId "com.reactnativepdfviewer"
-       minSdkVersion rootProject.ext.minSdkVersion
+       minSdkVersion 21
        targetSdkVersion rootProject.ext.targetSdkVersion
    }
}

Step 4 — Configuring the iOS platform

1. Open ios/Podfile and set the platform version to iOS 15:

- platform :ios, '11.0'
+ platform :ios, '15.0'

2. Navigate to the ios folder and install the required dependencies:

cd ios
pod install

3. Open the Workspace in Xcode:

open ReactNativePDFViewer.xcworkspace

4. In Xcode, ensure the deployment target is set to 15.0 or higher.

5. Change View controller-based status bar appearance to YES in Info.plist.

Step 5 — Displaying a PDF document

1. Drag a PDF document into your project to use as a sample.

2. *If you haven’t already, create an assets directory for Android:

mkdir android/app/src/main/assets

3. Place your PDF document in the assets directory:

cp ~/Downloads/Document.pdf android/app/src/main/assets/Document.pdf

4. Open App.js and replace its contents with the following code snippet:

import React, { Component } from 'react';
import { Platform } from 'react-native';
import PSPDFKitView from 'react-native-pspdfkit';
import { NativeModules } from 'react-native';

const PSPDFKit = NativeModules.PSPDFKit;
PSPDFKit.setLicenseKey(null);

const DOCUMENT =
	Platform.OS === 'ios'
		? 'Document.pdf'
		: 'file:///android_asset/Document.pdf';
export default class PSPDFKitDemo extends Component<{}> {
	render() {
		var pdfRef: React.RefObject<PSPDFKitView> = React.createRef();
		return (
			<PSPDFKitView
				document={DOCUMENT}
				configuration={{
					showThumbnailBar: 'scrollable',
					pageTransition: 'scrollContinuous',
					scrollDirection: 'vertical',
				}}
				ref={pdfRef}
				fragmentTag="PDF1"
				style={{ flex: 1 }}
			/>
		);
	}
}

Customizing the PDF viewer

Customizing the PDF viewer is essential for aligning it with your app’s aesthetic and enhancing the user experience. React Native PDF viewers offer several customization options, allowing you to tailor the viewer’s layout and functionality to suit your needs. You can modify the viewer’s appearance, adjust the layout, and add custom buttons. Additionally, you can personalize its behavior, such as setting the initial page, zoom level, and rotation. For instance, you might choose to start the PDF on a specific page or adjust the zoom level to fit the screen optimally. By leveraging these customization options, you can create a unique and engaging experience that aligns with your app’s branding and improves usability.

Handling PDF file downloads and storage

Handling PDF file downloads and local storage is critical for React Native apps that require offline access to PDF files. Libraries like react-native-fs can be used to download and store PDF files locally on a device, ensuring users can access documents without an internet connection. Implementing caching mechanisms for frequently accessed files can reduce the need for repeated downloads and improve performance. When managing PDF downloads and storage, consider factors like file size, storage limits, and security to maintain app performance and reliability. Proper management ensures a seamless user experience and reduces the risk of errors or inefficiencies.

Optimizing performance and user experience

Optimizing performance and user experience is essential for React Native PDF viewers. To achieve the best performance, you can employ techniques like lazy loading, which loads content only when needed, and caching, which stores frequently accessed data for quicker retrieval. These methods help reduce loading times and improve overall responsiveness. Additionally, optimizing image rendering can significantly enhance the viewer’s performance, particularly when dealing with large or high-resolution PDFs.

Libraries like react-native-pdf come with built-in mechanisms for optimized rendering and caching, making them a great choice for performance-focused applications. By focusing on these optimization techniques, you can ensure a fast, responsive PDF viewer that meets your users’ expectations and provides a seamless, smooth experience.

Step 6 — Launching the app

Run the app on your chosen platform:

npx react-native run-android
npx react-native run-ios

Troubleshooting and debugging

Troubleshooting and debugging are essential skills for React Native developers working with PDF viewers. Common issues like PDF files not loading, the viewer not rendering, and app crashes can be resolved by checking the PDF file path, verifying compatibility with the PDF viewer library, and ensuring sufficient device memory and storage capacity. Additionally, using debugging tools like React Native Debugger and Chrome DevTools can help identify and resolve issues more efficiently. By effectively troubleshooting and debugging, you can ensure a seamless user experience and quickly address any problems that arise, maintaining the reliability and performance of your React Native PDF viewer.

Conclusion

We hope this post will help you build a PDF viewer using react-native-pdf and Nutrient React Native SDK in your React Native project. As you can see, react-native-pdf is a great solution for many use cases.

However, sometimes your business may require more complex features for handling PDFs in your React Native project, such as:

• PDF annotation support — react-native-pdf will only render annotations that were already in the source file. It doesn’t have annotation editing support, so your users won’t be able to create, update, or delete annotations to review a PDF document.

• Interactive PDF forms — Just like with annotations, react-native-pdf will only render forms and their values that were already in the source file. It doesn’t have form editing support, so your users won’t be able to fill forms in a PDF document.

• Digital signatures — react-native-pdf currently has no support for digital signatures, which are used to verify the authenticity of a filled-out PDF.

• Long-term support — Currently, the latest update for react-native-pdf dates back to October 2020. At Nutrient, we release regular updates to add new features and enhancements, fix bugs, and maintain compatibility with the latest React Native changes, dependencies, and operating system updates.

If your business relies on any of the above features, consider looking into alternatives. At Nutrient, we offer a commercial, feature-rich, and completely customizable React Native PDF viewer library that’s easy to integrate and comes with well-documented APIs to handle advanced use cases. Check out our demos to see it in action.

If you have any questions about our React Native PDF library, please don’t hesitate to reach out to us. We’re happy to help!

FAQ

Here are a few frequently asked questions about building a React Native PDF viewer.