react-native-pdf-pro

A modern, dependency-free PDF viewer for React Native, built for the New Architecture from day one.

• Swift + Apple PDFKit on iOS — text search with highlights, night mode, passwords, links, table of contents, all first-party
• Kotlin + Jetpack androidx.pdf on Android — Google's official PDF viewer with built-in search, text selection, passwords, and link handling
• Zero third-party native dependencies — no bundled Pdfium, no JitPack forks, no 16 KB page-alignment problems on Google Play
• Built-in networking and caching — remote PDFs are downloaded natively with URLSession / OkHttp; no react-native-blob-util peer dependency
• Fabric native component with typed codegen props, events, and commands
• Expo compatible — works in development builds and with npx expo prebuild; no config plugin required (not supported in Expo Go, like all native code)

Why not react-native-pdf?

react-native-pdf is the incumbent, but it carries structural problems a fork can't fix: an Android render stack built on two layers of abandoned/forked third-party libraries (which caused the Google Play 16 KB alignment blocker), a fragile react-native-blob-util peer dependency responsible for a whole class of install and runtime crashes, long release gaps, and New Architecture codegen bugs. This library is a clean rewrite on first-party platform PDF engines with none of those moving parts.

Requirements

| | Minimum | |---|---| | React Native | 0.76+ (New Architecture) | | iOS | 15.1+ | | Android | API 28 (Android 9)+ |

Installation

npm install react-native-pdf-pro
# or
yarn add react-native-pdf-pro

Then cd ios && pod install (bare RN) or rebuild your dev client (npx expo prebuild && npx expo run:ios).

Android setup

The Jetpack androidx.pdf engine needs two values in your app's Gradle config:

// android/build.gradle
ext {
    minSdkVersion = 28 // Android 9+
}

// android/app/build.gradle, inside android { }
compileSdkExtension 19

Usage

import { useRef } from 'react';
import { PdfView, type PdfViewRef } from 'react-native-pdf-pro';

export function Reader() {
  const pdf = useRef<PdfViewRef>(null);

  return (
    <PdfView
      ref={pdf}
      style={{ flex: 1 }}
      source={{
        uri: 'https://example.com/document.pdf',
        headers: { Authorization: 'Bearer …' },
        cache: true,
      }}
      onLoad={({ pageCount, tableOfContents }) =>
        console.log(`Loaded ${pageCount} pages`, tableOfContents)
      }
      onPageChanged={({ page, pageCount }) =>
        console.log(`Page ${page} / ${pageCount}`)
      }
      onError={({ message }) => console.warn(message)}
    />
  );
}

Sources

source accepts a string, a require()'d asset, or an object:

<PdfView source="https://example.com/doc.pdf" />
<PdfView source="file:///path/to/doc.pdf" />
<PdfView source="data:application/pdf;base64,JVBERi0x…" />
<PdfView source="bundled-file.pdf" />          // iOS bundle / Android assets
<PdfView source={require('./doc.pdf')} />      // metro asset
<PdfView source={{ uri: '…', headers: { … }, password: '…', cache: false }} />

Props

| Prop | Type | Default | Platforms | Description | |---|---|---|---|---| | source | PdfSource | — | both | Document to display (see above) | | page | number | 1 | iOS | Initial page, 1-based; changing it navigates | | scale | number | 1 | iOS | Zoom relative to fit-to-screen | | minScale / maxScale | number | 1 / 4 | iOS | Zoom limits | | displayMode | 'singlePage' \| 'continuous' \| 'twoUp' \| 'twoUpContinuous' | 'continuous' | iOS | Page layout | | horizontal | boolean | false | iOS | Horizontal scrolling | | enablePaging | boolean | false | iOS | Snap to whole pages | | enableRTL | boolean | false | iOS | Right-to-left page order | | enableDoubleTapZoom | boolean | true | iOS | Double-tap to zoom | | enableAnnotations | boolean | true | iOS | Render embedded annotations | | nightMode | boolean | false | iOS | Invert page colors for dark reading | | pageSpacing | number | 8 | iOS | Space between pages (pt) |

Props marked iOS are accepted everywhere (no crashes on Android) — Android's Jetpack viewer manages its own layout, zoom, and password prompt UI. Parity is planned as androidx.pdf exposes more surface.

Events

| Event | Payload | Platforms | |---|---|---| | onLoad | { pageCount, width, height, tableOfContents } | both | | onLoadProgress | { progress } (0–1) | both | | onPageChanged | { page, pageCount } | iOS | | onError | { message } | both | | onPageSingleTap | { page } | iOS | | onScaleChanged | { scale } | iOS | | onLinkPressed | { url } | iOS | | onPasswordRequired | { reason } | iOS (Android shows its own dialog) | | onSearchResults | { totalMatches, currentIndex } | iOS |

Methods (via ref)

| Method | Description | Platforms | |---|---|---| | goToPage(page) | Scroll to a page | iOS | | search(term) | Highlight all matches and focus the first (iOS); open the native find-in-document UI (Android) | both | | searchNext() / searchPrevious() | Cycle through matches | iOS | | clearSearch() | Remove highlights / close search UI | both |

Table of contents

onLoad delivers the document outline as a tree:

type TableOfContentsEntry = {
  title: string;
  page: number; // 1-based, 0 if unknown
  children: TableOfContentsEntry[];
};

Caching

Remote documents are cached on disk (Caches/react-native-pdf-pro/ on iOS, cacheDir/react-native-pdf-pro/ on Android), keyed by the SHA-256 of the URL. Pass cache: false in the source object to always re-download. The OS is free to evict these directories when storage is low.

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT