With that, your project is now configured to use the react-native-pdf viewer. If you happen to be building with Expo, keep in mind that native modules sometimes have a different setup process. Our Expo React Native tutorial offers more detailed guidance on handling dependencies in that ecosystem.

Building a Functional PDF Viewer Component

Now for the fun part. Let's build a reusable TypeScript component to display our PDFs. This component will be smart enough to handle loading states, errors, and even basic page navigation.

We'll kick things off by defining the component structure and managing its state with hooks. This example shows how to render a PDF from a remote URL—a very common real-world scenario.

import React, { useState } from 'react'; import { StyleSheet, View, Text, ActivityIndicator } from 'react-native'; import Pdf from 'react-native-pdf';

const PDFViewer = () => { const [totalPages, setTotalPages] = useState(0); const [currentPage, setCurrentPage] = useState(1); const [isLoading, setIsLoading] = useState(true);

const source = { uri: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf', cache: true };

return ( <View style={styles.container}> {isLoading && <ActivityIndicator size="large" color="#0000ff" />} <Pdf source={source} onLoadComplete={(numberOfPages, filePath) => { setTotalPages(numberOfPages); setIsLoading(false); console.log(Number of pages: ${numberOfPages}); }} onPageChanged={(page, numberOfPages) => { setCurrentPage(page); console.log(Current page: ${page}); }} onError={(error) => { console.log(error); setIsLoading(false); }} onPressLink={(uri) => { console.log(Link pressed: ${uri}); }} style={styles.pdf} /> {!isLoading && ( <Text style={styles.pageNumber}> Page {currentPage} of {totalPages} </Text> )} </View> ); };

const styles = StyleSheet.create({ container: { flex: 1, justifyContent: 'center', alignItems: 'center', }, pdf: { flex: 1, width: '100%', height: '100%', }, pageNumber: { position: 'absolute', bottom: 10, backgroundColor: 'rgba(0,0,0,0.5)', color: 'white', padding: 5, borderRadius: 5, }, });

export default PDFViewer;

A Quick Tip: The source prop is incredibly versatile. It can handle a remote URI, a local file path (like require('./assets/my-document.pdf')), or even a base64 encoded string. This flexibility means you can load PDFs from just about anywhere.

This component gives you a solid foundation for any React Native PDF viewer feature. By gracefully handling the loading and error states, you're already ensuring a much smoother user experience, especially when network conditions aren't perfect. From here, you can easily extend it with custom buttons for page navigation or any other UI elements you need.

Moving Beyond a Basic PDF Viewer

Getting a PDF to show up on the screen is a great first step, but let's be honest—that's just the table stakes. A truly professional app needs to feel interactive and polished. Users expect to be in control, and that means we need to move beyond a simple static display and build a feature that elevates the entire experience.

So, how do we get there? I'll walk you through adding crucial controls like zooming, switching up the scroll behavior, and even jumping to specific pages on command. We'll also tackle real-world problems like handling password-protected files and using caching to make your app feel snappy and responsive.

Giving Users More Control and Better Navigation

A good user experience hinges on giving people intuitive control. Fortunately, the react-native-pdf library makes this pretty painless by exposing several props that let you fine-tune the viewer's behavior.

Here are a couple of quick wins:

• Zoom Functionality: You can easily set boundaries for how much a user can zoom. For instance, setting minScale={1.0} keeps them from accidentally zooming out too far, while maxScale={5.0} gives them plenty of room to magnify details.
• Scrolling Direction: The default scroll is vertical, but what if you're displaying a presentation or a digital magazine? A simple horizontal={true} prop flips the scrolling to a book-like swipe, which can dramatically improve the feel for that kind of content.

You don't have to stop there, either. You can build your own custom UI—like next and previous page buttons—and wire them directly into the viewer. Just grab a React ref to the <Pdf> component, and you can call its methods directly. A simple button press could then programmatically update the page prop, giving you full control over navigation.

Tackling Security and Performance Head-On

In the real world, you're not just dealing with simple, open documents. You'll run into sensitive files and large PDFs that can bog down your app if you're not careful.

Handling Password-Protected PDFs

Business documents like financial reports or contracts are often locked behind a password. The react-native-pdf library handles this gracefully with its password prop. All you need to do is build a UI that prompts the user for the password, then feed their input straight into the viewer component to unlock the file.

Pro Tip: When you're asking for a password, always use a secure text input field. Keep the password in a temporary state variable and pass it to the password prop. Whatever you do, never hardcode credentials directly in your source code.

Caching for a Faster Experience

Nobody wants to wait for the same PDF to download over and over again. It’s a waste of time and data. The library has a built-in fix for this: the cache property within the source object.

By setting source={{ uri: '...', cache: true }}, you're telling the component to save a local copy of the PDF right after it's downloaded the first time. The next time the user opens it, the viewer will grab the cached version, making it load almost instantly. For any app that shows the same documents repeatedly, this is a non-negotiable performance boost.

In the wider React ecosystem, having a solid PDF viewer is key for building high-performance apps. Many libraries support dynamic page rendering, which is a lifesaver for massive files. Enterprise-level tools go even further, offering annotations, form filling, and digital signatures—features that are absolutely essential for complex business workflows. These capabilities are what separate a basic document viewer from a powerful, interactive tool inside a React Native app. If you're curious about what else is out there, Syncfusion has a great breakdown of the best React PDF viewers.

Look, even the most buttoned-up integration can hit a snag. When your React Native PDF viewer decides to act up, knowing where to start poking around is half the battle. Think of this section as your field guide for squashing the most common bugs developers stumble into.

A lot of the time, the trouble boils down to something simple like a wrong asset path or a native linking failure. These often throw cryptic build errors or just give you a blank screen where your document should be. Let's walk through these common headaches and how to fix them.

Resolving File Path and Linking Errors

One of the most frequent pains is the classic "file not found" error, especially when you're dealing with local assets. It’s an easy mistake to make because Android and iOS handle local file paths just differently enough to be annoying.

On Android, if you've placed your assets in android/app/src/main/assets/, you have to reference them with the file:///android_asset/ prefix. Meanwhile, on iOS, you can usually get away with just the filename, assuming it’s bundled correctly in your Xcode project. Always double-check that source prop to make sure the path is right for the platform you're testing on.

Another classic is the iOS build failure right after you install a native module. This is almost always a sign that the native dependencies didn't link up correctly.

• Run pod install: This should be muscle memory. After adding a new native library, cd into your ios directory and run pod install.
• Clean the Build Folder: Sometimes Xcode just gets stuck. Go to Product > Clean Build Folder. You'd be surprised how often this clears up weird, unexpected build failures.
• Check Podfile.lock: Make sure your Podfile is set up correctly and that you don't have any version conflicts clashing with your other libraries.

Key Takeaway: Most build and runtime errors with a react-native-pdf viewer trace back to configuration. Before you start tearing apart your component logic, systematically check your native linking on iOS and file permissions on Android.

Tackling Performance and Permission Problems

So, what if the viewer actually works, but it’s painfully slow or hitting weird platform-specific walls? Large PDFs, especially those packed with high-res images, can create serious performance bottlenecks, leaving you with slow rendering and a janky UI.

To fight this, turn on caching. Just set cache: true in your source object. This tells the library to download the file once and then load it from local storage for any future views, which makes a massive difference in speed. If you're dealing with truly massive files, see if your library supports lazy loading or rendering pages on demand.

On newer Android versions, scoped storage is another common culprit for permission errors. If your app is flat-out denied access to a file, you need to make sure you've requested the right permissions in your AndroidManifest.xml. You also need to handle the runtime permission requests correctly in your app's logic. This is absolutely critical if you're trying to load documents from anywhere outside your app's sandboxed storage.

Common Questions About PDF Viewers in React Native

As you start wrapping things up, a few questions almost always pop up. Let's tackle some of the most common ones I've run into when building a react native pdf viewer.

Can I Fill Out PDF Forms in React Native?

This one really comes down to the library you pick. Your standard open-source options, like react-native-pdf, are great for just displaying a document. You’ll see the form fields, but they won't be interactive—users can look, but they can't type.

If you actually need form-filling capabilities, you're going to have to look at a more advanced, and often commercial, SDK. These are the tools that give you the robust APIs needed to handle user input, grab that form data, and save the updated PDF. It's an absolute must for most business or enterprise apps.

How Do I Handle Annotations?

This is a similar story to forms. Most viewers can show existing annotations just fine—any highlights, notes, or drawings already baked into the PDF will appear. But letting your users create, edit, or delete those annotations right inside the app? That's a whole other level.

If marking up documents is a core feature for your app, you'll need to hunt down a library built specifically for it. These tools come packed with a full UI for adding notes and the APIs to manage all that annotation data behind the scenes.

Remember, features like interactive forms and live annotation editing are what turn a simple document display into a genuinely powerful in-app tool. Always dig into a library's documentation to confirm it supports these specific features before you commit to it.

What's the Best Way to Load Large PDF Files?

Dealing with big, clunky PDFs is a classic performance headache. The single best thing you can do is enable caching wherever the library supports it. Just by setting cache: true in your source prop, the file gets downloaded once and then pulled from local storage for every subsequent view. It’s a game-changer for load times.

For those massive, complex documents, you should also look for libraries that support on-demand page rendering. You might see it called "lazy loading"—it only renders the pages the user is actually looking at, which massively cuts down on initial memory use and keeps your app feeling snappy.

Ready to skip the headaches and build a high-performance app with a feature-rich PDF viewer? theappmarket offers production-ready React Native templates that give you a massive head start.

Explore our templates and ship your app faster