custom-react-pdf-viewer

A production-ready React wrapper around Mozilla's pdf.js that provides a "drop-in" PDF viewer with a fully-featured toolbar, find bar, and automatic state persistence.

Features

• Batteries Included: Full toolbar with page navigation, zoom, rotation, print, download, and fullscreen out of the box.
• State Persistence: Automatically saves and restores scroll position (precise ratio), zoom level, and rotation for each document.
• Find Bar: Ctrl+F / Cmd+F support with highlighting, match case, and whole word options.
• Feature Flags: Easily opt-out of specific features (e.g., disable rotation or the toolbar) via props.
• Simple API: Just pass a File, Blob, or URL string.
• TypeScript: First-class type definitions included.

Installation

# npm
npm install custom-react-pdf-viewer

# pnpm
pnpm add custom-react-pdf-viewer

# yarn
yarn add custom-react-pdf-viewer

Requirements: react and react-dom (>=18 <20) are peer dependencies — provide them from your app (you almost certainly already have them). pdf.js is pulled in automatically as a pinned dependency, so there's nothing extra to install; it's pinned to an exact version (currently 6.0.227) rather than a range because the viewer integrates deeply with pdf.js internals and ships its stylesheet built against that exact release, so it's bumped deliberately with each version.

Usage

Level 1: The Simplest Use-Case

If you just want to render a PDF without worrying about state or persistence, simply import the component and pass it a file.

Note:* The viewer is designed to fill 100% of the width and height of its parent container. Ensure the parent element has a defined height (e.g., 100vh, 500px, or flex: 1).

import { CustomPdfViewer } from "custom-react-pdf-viewer";
import "custom-react-pdf-viewer/style.css"; // Don't forget the styles!

function SimpleViewer({ fileBlob }) {
  return (
    <div style={{ height: "100vh" }}>
      <CustomPdfViewer
        file={fileBlob}
        fileName="my-document.pdf"
      />
    </div>
  );
}

Level 2: Enabling State Persistence

To automatically remember zoom levels and scroll positions when users switch between documents, you need two things:

1. Wrap your app with the <PdfStoreProvider>.
2. Give your viewer a unique viewerId.

Step A: Add the Provider

// src/main.tsx
import { PdfStoreProvider } from "custom-react-pdf-viewer";

<PdfStoreProvider>
  <App />
</PdfStoreProvider>

Step B: Use the Viewer with an ID

// src/App.tsx
import { CustomPdfViewer } from "custom-react-pdf-viewer";

function App() {
  // ... file loading logic ...

  return (
    <CustomPdfViewer
      file={file}
      fileName="sample.pdf"
      // 1. Required: Unique ID for this UI slot (e.g. "main-viewer", "sidebar")
      viewerId="main-pdf-viewer"
      // 2. Recommended: Unique ID for the document content
      sessionKey="doc-123"
    />
  );
}

Result: If a user zooms to 150%, switches to another document, and returns to "doc-123", the viewer will automatically restore the zoom level and exact scroll position.

Level 3: Persisting Across Reloads (LocalStorage)

By default, the PdfStoreProvider uses in-memory storage, meaning state is lost on refresh.

To persist state across browser restarts, pass LocalStorageStore to the provider.

import { PdfStoreProvider, LocalStorageStore } from "custom-react-pdf-viewer";

<PdfStoreProvider store={new LocalStorageStore()}>
  <App />
</PdfStoreProvider>

The component usage (viewerId, sessionKey) remains exactly the same as in Level 2.

Component Props

| Prop | Type | Description | |--------------------|---------------------------------------|-------------| | file | Blob \| File \| string \| null | Required. The source of the PDF. | | fileName | string | Optional. The name shown in the toolbar and used for downloads. | | documentTitle | string | Optional. Overrides the displayed title. Defaults to fileName. | | viewerId | string | Required for persistence. Unique identifier for this viewer slot. | | sessionKey | string | Optional. Identifies the document; if it changes, the viewer treats it as a new document. | | persistenceStore | PdfPersistenceStore | Optional. Store override for this instance; falls back to the PdfStoreProvider context. | | disabledFeatures | string[] | Optional. Features to hide: "toolbar", "find", "rotation", "zoom", "pagination", "print", "download". | | highlightInfo | { [page: number]: string } \| null | Optional. Text to highlight, keyed by page number. | | jumpToPage | number \| null | Optional. Programmatically scroll to a page. | | iconSet | IconSet | Optional. Icon set for the toolbar and menu. Defaults to Lucide. | | toolbarSize | 'sm' \| 'md' \| 'lg' | Optional. Toolbar size preset. Defaults to 'md'. | | onOpen | () => void | Optional. Wires the menu's "Open" item; omit to hide it. | | onClose | () => void | Optional. Wires the menu's "Close" item; omit to hide it. | | allowDownload | boolean | Optional. Allow downloading the document. Default true. | | allowPrint | boolean | Optional. Allow printing the document. Default true. | | allowFullscreen | boolean | Optional. Allow toggling fullscreen. Default true. |

Disabling Features

<CustomPdfViewer
  file={file}
  disabledFeatures={['rotation', 'find']}
/>

Styling

:root {
  /* Toolbar & Backgrounds */
  --custom-pdf-toolbar-bg: #f9f9fa;
  --custom-pdf-toolbar-border-color: #b8b8b8;
  --custom-pdf-viewer-bg: #f1f5f9;
  --custom-pdf-main-color: #181819;

  /* Accent Colors */
  --custom-pdf-accent-color: #0a84ff;
  --custom-pdf-button-hover-color: #ddd;
}

License

Apache-2.0 © Roland Arnold