Note

To try React PDF kit library for free, simply follow the instruction in the docs. For commercial use, please purchase a license.

Prerequisites

To run a React PDF Viewer component in an application, here is the basic system requirement:

• React version: >= 18.0
• React version: >= 19.0

Remark: If using TypeScript, it requires >= TypeScript 4.6.

React PDF Kit works not only with a React framework such as Next.js (App Router and Pages Router), Remix and Gatsby but also works well with other React.js UI libraries such as MUI, Ant Design and Chakra UI.

Although React PDF can run on most JavaScript module bundlers, it is more vigorously tested on Vite and Webpack.

Browser support

Starting from @react-pdf-kit/viewer@^2.0.0, we officially support PDF.js 5 and default to PDF.js 5.4.530.

As newer PDF.js versions rely on more modern browser APIs, minimum supported browser versions have changed. Please review the compatibility details below before choosing a PDF.js version.

Default (PDF.js 5.4.530)

React PDF Kit v2.0.0 defaults to PDF.js 5.4.530.

Configuration	Chrome	Firefox	Edge	Safari	Safari iOS	Chrome Android
React PDF Kit v2	126+	126+	126+	18.4+	18.4+	126+
React PDF Kit v2 + Polyfills	119+	121+	119+	18.3+	18.3+	119+
React PDF Kit v2 + Polyfills + Legacy PDF.js Worker	101+	101+	101+	16.5+	16.5+	101+

To change the version of PDF.js used, refer to Dependency Override guide.

Note

It’s currently not recommended to use a PDF.js worker version beyond 5.4.530 because it will support fewer browser versions.

Installation

Install React PDF Kit

There are a few ways you can install React PDF Kit, namely bun, npm, pnpm or yarn.

bun

To install using bun, run:

bun add @react-pdf-kit/viewer

Remark: From v2 onwards, a new NPM package is used. To install v1 of React PDF, please run with @react-pdf-kit/viewer.

Caching of previous Worker version with bun

To clear cache, try running bun pm cache rm to remove cache in the global cache directory. If the error remains, try executing the following steps:

rm bun.lockb
rm -R node_modules

Please ensure that you follow this step if you want to override pdfjs-dist version. After that, you may execute this command to install all dependencies again.

bun i

npm

To install using npm, run:

npm install @react-pdf-kit/viewer

pnpm

To install using pnpm, run:

pnpm add @react-pdf-kit/viewer

yarn

To install using yarn, run:

yarn add @react-pdf-kit/viewer

Installation Issues

Apple M series

Since the default version of pdfjs-dist in React PDF requires the canvas package, you may need to manually add the canvas package for Apple M1 and later chipsets.

You may use Brew, a popular package manager to install the canvas dependencies:

$ brew install pkg-config cairo pango

Peer Dependencies

The React PDF Viewer component requires PDF.js (pdfjs-dist) as a peer dependency with a default version of 5.4.530.

You may override the default pdfjs-dist within React PDF Kit. For more information, refer to Dependency Override.

Bundler Compatibility

pdfjs-dist v5 is ESM-only. Most modern bundlers handle this without any configuration:

• Vite — works out of the box
• Turbopack (Next.js 15+) — works out of the box
• Webpack 5 — works with proper ESM support enabled

Exception: Next.js 14 (Webpack). Next.js 14 has a known ESM interop bug that causes pdfjs-dist v5 to fail at module load time:

TypeError: Object.defineProperty called on non-object

If you are using Next.js 14, override pdfjs-dist to v4, which supports both ESM and CommonJS. See Dependency Override for more information.

PDF.js asset URLs

Most PDF files work without extra asset configuration. However, some documents need additional PDF.js files at runtime, especially when they contain JPEG 2000 images or embedded color profile data.

• Use wasmUrl to point PDF.js to its WebAssembly assets. This is commonly needed for PDFs that contain JPEG 2000 images.
• Use iccUrl to point PDF.js to its ICC color profile files. This helps PDF.js render documents that depend on external color profiles.
• Use standardFontDataUrl to point PDF.js to its standard font data directory. This helps PDF.js render documents that rely on PDF.js standard fonts.

Note: iccUrl requires wasmUrl because PDF.js uses WebAssembly for ICC color profile support.

The asset URLs should always match the pdfjs-dist version installed in your project. React PDF Kit defaults to PDF.js 5.4.530, so you can use these hosted asset directories:

<RPConfig
  wasmUrl="https://unpkg.com/pdfjs-dist@5.4.530/wasm/"
  iccUrl="https://unpkg.com/pdfjs-dist@5.4.530/iccs/"
  standardFontDataUrl="https://unpkg.com/pdfjs-dist@5.4.530/standard_fonts/"
>

You only need to set these props once, on the root RPConfig component. See the RPConfig component reference for the full list of configuration options.