Events

React to the document loading, pages rendering and the user navigating, for analytics, logging or your own UI.

Basics

Pass callbacks to hear what the viewer is doing.

import { PdfViewer } from '@kingtech/react-pdf-viewer'; import { useState } from 'react'; export default function Demo() { const [log, setLog] = useState<string[]>([]); const record = (line: string) => setLog((previous) => [line, ...previous].slice(0, 8)); return ( <> <PdfViewer source="/samples/multipage.pdf" onDocumentLoad={({ numPages, fingerprint }) => record(`onDocumentLoad: ${numPages} pages, ${fingerprint.slice(0, 8)}…`) } onPageRender={({ page, scale, durationMs }) => record( `onPageRender: page ${page} at ${Math.round(scale * 100)}% in ${Math.round(durationMs)} ms`, ) } onPageChange={(page) => record(`onPageChange: ${page}`)} onScaleChange={(scale) => record(`onScaleChange: ${scale}`)} /> <pre className="demo-output" aria-label="Event log"> {log.length ? log.join('\n') : 'Waiting for events…'} </pre> </> ); }

Callback	Called with	When
`onDocumentLoad`	`{ numPages, fingerprint }`	A document finished loading
`onPageRender`	`{ page, scale, width, height, durationMs }`	A page finished rendering
`onPageChange`, `onScaleChange`, `onRotationChange`, `onFullscreenChange`	the new value	The user or your code changed it; see Controlled state
`onError`	`PdfViewerError`	Something failed; see Error states
`onDownload`, `onPrint`	the file, or nothing	Before saving or printing; return `false` to take over
`onHttpError`	`Response`	A URL source returned a non-2xx status

fingerprint identifies the document’s content, which is handy as a cache or analytics key. Callbacks can change between renders without reloading anything.

Customization

Use render measurements to drive your own UI, such as a status bar.

import { PdfViewer, type PageRenderInfo } from '@kingtech/react-pdf-viewer'; import { useState } from 'react'; export default function Demo() { const [last, setLast] = useState<PageRenderInfo | null>(null); return ( <> <p className="demo-output" role="status"> {last ? `Page ${last.page}: ${Math.round(last.width)} × ${Math.round(last.height)} px, rendered in ${Math.round(last.durationMs)} ms` : 'Render a page to measure it.'} </p> <PdfViewer source="/samples/mixed-sizes.pdf" onPageRender={setLast} zoomReset /> </> ); }

See the customization guide.

Advanced / escape hatch

PdfPageCanvas has its own onRender and onError for headless layouts.

Limitations

No scroll or selection events. The viewer does not report scroll position or text selection. Workaround: listen on the document area yourself (.rpv-viewport) or use document.getSelection() with the text layer.
onPageRender fires often. It fires after every render, including re-renders after zoom and resize. Workaround: debounce it before sending analytics.

API

PageRenderInfo — Details of a completed page render, passed to onPageRender and onRender: the page, the scale used, its size and the time it took.