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, page navigation, zoom, and rotation 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

Note: This package requires react and react-dom (>=18) as peer dependencies.

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 to display in the toolbar. | | viewerId | string | Required for persistence. Unique identifier for this viewer instance. | | sessionKey | string | Optional. Ensures state is restored only for the correct document. | | disabledFeatures | string[] | Optional. Features to hide: "toolbar", "find", "zoom", "pagination". | | isLoading | boolean | Optional. Force the loading spinner state. |

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