Headless

Build a completely custom PDF interface from the same document loader and page renderer the viewer uses.

PdfViewer is assembled from two public building blocks. Use them directly when your layout is not a toolbar and a page: comparison views, galleries, spreads, or pages embedded in a larger UI.

Basics

usePdfDocument(source) loads a document; PdfPageCanvas renders one of its pages.

import { PdfPageCanvas, usePdfDocument } from '@kingtech/react-pdf-viewer'; import { useState } from 'react'; export default function Demo() { const { status, document, numPages, error, reload } = usePdfDocument('/samples/multipage.pdf'); const [page, setPage] = useState(1); if (status === 'error') { return ( <p role="alert"> {error?.message}{' '} <button type="button" onClick={reload}> Retry </button> </p> ); } if (status !== 'ready' || !document) return <p role="status">Loading…</p>; return ( <div style={{ display: 'grid', gridTemplateColumns: '120px 1fr', gap: 16, alignItems: 'start' }} > <ol aria-label="Pages" style={{ listStyle: 'none', margin: 0, padding: 0, maxHeight: 520, overflow: 'auto' }} > {Array.from({ length: numPages }, (_, index) => index + 1).map((n) => ( <li key={n}> <button type="button" aria-current={n === page ? 'page' : undefined} onClick={() => setPage(n)} style={{ border: n === page ? '2px solid #1d4ed8' : '2px solid transparent', background: 'none', padding: 2, }} > <PdfPageCanvas document={document} page={n} fit={{ width: 96 }} aria-label={`Page ${n}`} /> </button> </li> ))} </ol> <PdfPageCanvas document={document} page={page} fit={{ width: 520 }} aria-label={`Page ${page} of ${numPages}`} /> </div> ); }

usePdfDocument returns { status, document, numPages, error, reload }. It handles fetching, aborting when the source changes, HTTP errors and destroying documents, and never exposes a destroyed document. It accepts the same sources and request options as the viewer.

PdfPageCanvas renders with cancellation, double buffering, HiDPI output and the pixel budget. It sizes itself from scale, or from a fit box ({ width, height, upscale }), adds the page’s intrinsic rotation to rotation, and can render textLayer and annotationLayer.

Customization

Combine the pieces into layouts the viewer does not offer, such as a two-page spread with highlighted matches.

import { PdfPageCanvas, usePdfDocument } from '@kingtech/react-pdf-viewer'; import { useState } from 'react'; /** A two-page spread with highlighted search matches, built from the headless pieces. */ export default function Demo() { const { document, numPages } = usePdfDocument('/samples/multipage.pdf'); const [left, setLeft] = useState(1); const [query, setQuery] = useState('viewer'); if (!document) return <p role="status">Loading…</p>; return ( <> <p className="demo-controls"> <button type="button" disabled={left <= 1} onClick={() => setLeft((p) => Math.max(1, p - 2))} > ← Previous spread </button> <button type="button" disabled={left + 2 > numPages} onClick={() => setLeft((p) => p + 2)}> Next spread → </button> <label> Highlight <input value={query} onChange={(event) => setQuery(event.target.value)} /> </label> </p> <div style={{ display: 'flex', gap: 12, justifyContent: 'center', flexWrap: 'wrap' }}> {[left, left + 1] .filter((n) => n <= numPages) .map((n) => ( <PdfPageCanvas key={n} document={document} page={n} fit={{ width: 320 }} textLayer highlight={{ query, selected: null }} aria-label={`Page ${n} of ${numPages}`} /> ))} </div> </> ); }

Style pages with the same --rpv-page-* variables as the viewer; see the customization guide.

Accessibility in headless layouts

Give each PdfPageCanvas an aria-label (“Page 3 of 10”) so it is exposed as an image, or as a group containing its text and links when textLayer or annotationLayer is on; without a label it is decorative. Keyboard navigation, focus management and live announcements are yours to provide.

Advanced / escape hatch

document is a PDF.js PDFDocumentProxy: anything PDF.js can do (metadata, outline, text extraction, annotations) is available from it.

Limitations

No toolbar, shortcuts or fullscreen. Headless pieces render pages only. Workaround: use PdfViewer with renderToolbar if you only need a different toolbar.
One usePdfDocument per document. Each hook call loads its own copy. Workaround: load once near the top of your tree and pass document down.
Many canvases cost memory. Rendering dozens of full-size pages at once is expensive. Workaround: render thumbnails with a small scale or fit, and mount large pages only when visible.

API

usePdfDocument — Loads a PDF document. Every source change aborts the previous fetch, discards its result and destroys the previous document; unmounting does the same.
UsePdfDocumentOptions — Options for usePdfDocument. Changes apply on the next load, except password.
UsePdfDocumentResult — State returned by usePdfDocument: the load status, the document once ready, its page count, the error and a reload function.
PdfPageCanvas — Renders a single PDF page: cancellable, double-buffered, HiDPI and pixel-capped, with optional text and annotation layers.
PdfPageCanvasProps — Props for PdfPageCanvas: the document and page to render, its scale, rotation and fit, the optional layers and the render callbacks.