Skip to content

About

Native, virtualized PDF viewer for React Native, built on Nitro Views

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

95 stars

Watchers

0 watching

Forks

Repository files navigation

react-native-better-pdf

On Android, your react-native-pdf screen ships its own PDFium and peaks at 550 MB on a 500-page scan? Use the PDF engine the OS already has.

A replacement for react-native-pdf: PDFKit on iOS, the platform PdfRenderer on Android, rendered natively through Nitro Views. No bundled PDFium, no WebView, no react-native-blob-util, and no JS in the scroll, zoom and render path.

npm version npm downloads GitHub stars New Architecture License: MIT CI

Benchmark • Migration • Installation • Usage • Documentation • Example app

Two side-by-side scenes on Android, react-native-better-pdf 1.2 against react-native-pdf 7.0.5. Opening a 1,000-page scan: the first page is on screen 0.3 s after the tap against 4.5 s. Scrolling it: 99 to 138 MB of memory in use against 877 to 900 MB
react-native-better-pdf 1.2.0 (built from 1c286a8, which has the same Android code) and react-native-pdf 7.0.5 in the same app, release builds on the Android emulator (API 37), with the same 1,000-page scan, already in the disk cache: opening it, then scrolling it with the app's memory (PSS) sampled about every 0.7 s. Each side is the median of 3 takes. The first scene plays at real speed and the second at 2×; the times shown are real seconds. Recorded on 2026-11-06: that day's benchmark runs took 1.6 to 4.6 s for react-native-pdf to open this document, against 0.6 s in the table below.

Benchmark

The same app, the same documents and the same layout for both libraries. Medians of 3 runs of release builds on the Android emulator (API 37), both libraries in one session, from the benchmark harness:

Document Time to onLoad Peak memory (PSS) CPU while scrolling (all cores)
10 pages, text react-native-pdf 7.0.5 67 ms 90 MB 33%
react-native-better-pdf 57 ms 85 MB 16%
100 pages, images react-native-pdf 7.0.5 165 ms 130 MB 59%
react-native-better-pdf 43 ms 128 MB 26%
500 pages, scans react-native-pdf 7.0.5 417 ms 550 MB 111%
react-native-better-pdf 47 ms 104 MB 29%
1,000 pages, scans react-native-pdf 7.0.5 622 ms 898 MB 111%
react-native-better-pdf 56 ms 142 MB 34%
  • Memory. react-native-pdf's peak grows with the document: 550 MB at 500 pages, 898 MB at 1,000. Here it stays between 85 and 142 MB, bounded by the pages around the viewport. Pages that are all grey (text, greyscale scans) are kept in one byte per pixel.
  • Size. Native code and dex for one Android ABI: ≈ 2.1 MB, against ≈ 5.3 MB for react-native-pdf with its bundled PDFium, AndroidPdfViewer, Gson and react-native-blob-util. react-native-nitro-modules adds ≈ 1 MB, shared by every Nitro module in the app.
  • Load. onLoad fires once the document is open and the first page's size is known, before that page is drawn. react-native-pdf fires onLoadComplete after its own load.

Measured on an emulator: compare the libraries, not the absolute times. Frame times there are the same for both libraries, so comparing jank needs a device. On iOS both libraries render with PDFKit, so loads and memory are close, and this library links more code: 526 KB against 161 KB, most of it generated bindings. The benchmarks describe the method, and the full results include every run and the iOS numbers.

Migration

Remove react-native-pdf (and react-native-blob-util, unless something else in your app uses it), install this library, then:

- import Pdf from 'react-native-pdf';
+ import { PdfView } from 'react-native-better-pdf';

- <Pdf
-   source={{ uri: 'https://example.com/file.pdf', cache: true }}
+ <PdfView
+   source={{ uri: 'https://example.com/file.pdf', cache: 'persistent' }}
-   onLoadComplete={(numberOfPages) => setPageCount(numberOfPages)}
-   onPageChanged={(page, numberOfPages) => setPage(page)}
-   onError={(error) => console.warn(error)}
+   onLoad={({ pageCount }) => setPageCount(pageCount)}
+   onPageChange={({ page, pageCount }) => setPage(page + 1)}
+   onError={(error) => console.warn(error.code, error.message)}
    style={{ flex: 1 }}
  />

Callbacks take one event object, and page counts from 0. Migrating from react-native-pdf maps every prop, callback and method, and lists what changes silently.

Fixes over react-native-pdf

Issue Status
Android 16 KB page size (#960 and others) Native library 16 KB aligned
New Architecture / Fabric (#878 and others) Built for Fabric on Nitro Views
react-native-blob-util crashes and setup (#796 and others) Not used: downloads are native
Android "Already closed" crashes (#830 and others) Closing a document while it renders, searches or exports is handled and stress-tested
Link taps on Android (#983 and others) Every link form on every Android version (password-protected documents: see Limitations)
Search (#555 and others) Built in, with highlights (Android: see the capability matrix)
Viewport events, restoring the position (#492 and others) onViewportChange, initialViewport, goToViewport
Filling in and saving forms (#748 and others) Fill, read and export (Android: see the capability matrix)
Cache control and offline reading (#952 and others) Cache options on the source, PdfCache

The full list, with reaction counts, is in Community requests.

Caution

Search, text selection, password-protected documents and filling in forms need Android 15, or Android 12–14 with SDK extension 13 (the PDF module updated through Google Play system updates). On other Android versions a password-protected document fails with unsupported-pdf, search reports isSupported: false, long presses select nothing and forms are read only. See the capability matrix.

Installation

iOS 15.1+ and Android 7.0+ (API 24), React Native 0.83+ with the New Architecture, and react-native-nitro-modules 0.37.0+. Expo SDK 55+ needs a development build; Expo Go does not work.

npm install react-native-better-pdf react-native-nitro-modules
cd ios && pod install && cd ..

Rebuild the native app after installing. With Expo, install with npx expo install instead. No config plugin is needed: run npx expo prebuild, then npx expo run:ios or run:android. See Compatibility for the tested versions and what each Android version supports.

Usage

import { PdfView } from 'react-native-better-pdf';

export function Reader() {
  return (
    <PdfView
      style={{ flex: 1 }}
      source={{ uri: 'https://example.com/report.pdf' }}
      onLoad={({ pageCount }) => console.log('pages', pageCount)}
      onPageChange={({ page, pageCount }) => console.log(page + 1, '/', pageCount)}
      onError={(error) => console.warn(error.code, error.message)}
    />
  );
}

PdfView takes every View prop. source also takes a local file, a bundled require(), a content:// URI, { base64 }, or an array of sources shown as one document: see Sources and loading.

Documentation

API reference Every prop, ref method, object, error code and type
Sources and loading Remote, local and bundled files, content:// URIs, request headers and redirects, base64 data, several files as one document, loading state
Navigation and reading position Links and page taps; saving and restoring where the reader left off
Offline reading and caching Cache modes, revalidation with ETag / Last-Modified, offline fallback, PdfCache
Layout and appearance Facing pages, translucent bars, dark pages
Search Native full-text search with highlights
Forms Filling in, reading and exporting form fields
Page overlays React views attached to points of a page, moved natively while it scrolls and zooms
Page images and documents without a view Page images, covers and metadata with PdfDocument
Printing The system print dialog
Accessibility VoiceOver and TalkBack read each page's text (on Android below 15 without SDK extension 13, its label only)
Compatibility Requirements, tested versions and what each Android version supports
Migrating from react-native-pdf Every prop, callback and method, what changes silently, and common migrations
Limitations Known platform constraints and what's next
Troubleshooting Expo Go, New Architecture errors, documents that fail to open
Performance Benchmark method and results, including where this library is not faster
Architecture Threading, virtualization, cache and lifecycle
Example app Every feature on generated documents, the benchmark screen and the Maestro flows

Design notes: API design, platform research, the audit and community requests.

AI coding agents learn this API and the migration from react-native-pdf with the agent skill: npx skills add gmi-software/better-skills --skill react-native-better-pdf.

Contributing

See CONTRIBUTING.md for the toolchain, tests, end-to-end flows, benchmarks and commit conventions. Releases are published from CI, see RELEASING.md. Report vulnerabilities privately, see SECURITY.md.

License

MIT, see LICENSE.


Built and maintained by GMI Software. If it saves your PDF screen, a ⭐ helps other React Native developers find it.

About

Native, virtualized PDF viewer for React Native, built on Nitro Views

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

95 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages