parapdf
v0.9.0
Published
A fast PDF viewer for React, built on pdf.js
Maintainers
Readme
ParaPDF
A fast PDF viewer for React, built on pdf.js.
Status: 0.x. The API may change in any minor release until 1.0. parapdf.yhay81.com has the guides, the API reference, and a live demo.
- React stays out of the hot path. Scrolling and zooming commit no React state per frame, and pixels never pass through React.
- Only what is near the viewport exists. Pages outside a small window unmount. Each page draws a quick base first and full resolution once scrolling settles, and at high zoom only its visible part sharp, within pixel budgets you can set.
- Pages you come back to show at once. A page that leaves the window keeps its canvases, within a budget.
- Several viewers, one document. Each viewer has its own position, zoom, rotation, and layout; the document is opened, parsed, and searched once.
- A document viewer. Selectable, accessible text; search that matches as pdf.js's viewer does, CJK text included; links, the outline, and history; forms, annotations, printing, saving, layers, attachments, thumbnails, spreads, scroll modes, and encrypted documents.
- You load what you use. Forms (
<PdfForms />), annotation editing (<PdfAnnotationEditor />), auto-linked addresses (<PdfAutoLinks />), search, printing, and the other features are in your bundle only when you import them. - pdf.js included. ParaPDF ships pdf.js's worker and the files it loads on demand, and your bundler serves them: there is nothing to set up.
Install
npm install parapdfParaPDF needs React 19.3 or later. It depends on pdfjs-dist 6.5.438 exactly, because it ships that version's worker and files.
Quick start
import { PdfDocument, PdfViewer } from "parapdf";
export function App() {
return (
<PdfDocument source="/manual.pdf">
<PdfViewer style={{ height: "100vh" }} />
</PdfDocument>
);
}PdfDocument opens the document and provides a viewer for everything inside
it; PdfViewer is a scroll container that shows it. Give the viewer a
definite height: it does not grow with the document. Nothing suspends, and
the viewer shows no loading state or error of its own; read them with
useDocumentState().
Controls inside PdfDocument read the viewer and its state directly:
import { PdfDocument, PdfViewer, useViewer, useViewState } from "parapdf";
function Toolbar() {
const viewer = useViewer();
const { currentPage, pageCount } = useViewState();
return (
<div>
<button type="button" onClick={() => viewer.previousPage()}>Previous</button>
<span>{currentPage + 1} / {pageCount}</span>
<button type="button" onClick={() => viewer.nextPage()}>Next</button>
<button type="button" onClick={() => viewer.zoomBy(1.25)}>Zoom in</button>
</div>
);
}
export function Reader() {
return (
<PdfDocument source="/manual.pdf">
<Toolbar />
<PdfViewer style={{ height: "80vh" }} />
</PdfDocument>
);
}Bundlers
ParaPDF refers to pdf.js's worker and files with new URL(…, import.meta.url),
which Vite, webpack, Rsbuild, and Next.js (Turbopack and webpack) copy to the
build output as they are. With bundlers that do not, such as Parcel, esbuild,
and Bun, copy node_modules/parapdf/pdfjs/ to where your application serves
static files and tell ParaPDF where it is:
configurePdfjs({ assetBase: "/pdfjs/" });Bundlers covers Content Security Policy and files served from another origin.
Documentation
- Getting started and controls
- Guides: layout, search, navigation, forms, annotations, and more
- Reference: components, options, state, viewer, and sources
- Server rendering, accessibility, and limitations
- Changelog
License
Apache License 2.0. Parts of ParaPDF are derived from pdf.js: see NOTICE.md.
