Host element the canvas is appended to; it is made
position: relative if statically positioned so overlays (context menu)
can anchor to it. Size the viewer by sizing this element.
See PdfrxViewerOptions.
The cover scale: the zoom at which the whole
document's bounding box covers the viewport, i.e. max(viewW / docW, viewH / docH). In the default vertical layout this is effectively the
fit-document-width scale — you cannot zoom out past it and still fill the
viewport horizontally. Returns 1 before a document is laid out.
The page (1-based) currently covering the largest visible area, or null.
The current view transform (uniform zoom + pan). Document→view mapping used throughout the viewer.
The current logical viewport size in pre-CSS-transform pixels. Save this together with currentTransform when a view must later be restored with the same composition into a differently sized viewer.
The currently open PdfDocument, or null before the first open.
The engine backing this viewer. Use it to open other documents in the same worker — e.g. to convert an image to a PDF, or to import pages from a dropped file into document (cross-document page import only works within one engine). Shared if an PdfrxViewerOptions.engine was supplied.
Whether the PDF permission flags allow annotation and form modifications.
Whether copying the document's text is permitted. Mirrors pdfrx: a document
with no encryption/permissions allows copying, and an encrypted document
allows it unless its permissions explicitly forbid it
(PdfPermissions.allowsCopying is false).
Whether the PDF permission flags allow page insertion, removal and rearrangement.
Whether a document is currently opening. While this is true the previous document is not painted — parsing a large PDF takes seconds, and leaving the old one on screen makes the viewer look stuck.
Whether the PDF permission flags allow printing.
The current page-layout direction. See setLayoutDirection.
Download progress of the document being opened, or null when nothing is
loading or the source reports no byte counts (e.g. openData).
Number of pages in the current document, or 0 when none is open.
The plain text of the current selection (empty string when nothing is selected). Only pages whose text has already loaded contribute; text is composed across pages in reading order.
A snapshot of the current text selection.
Current built-in spread mode.
The current zoom factor (1 = 72 DPI, one PDF point per CSS pixel).
The active zoom mode. Numeric values are explicit zoom factors; 'page'
and 'width' remain active across viewport resizes.
Subscribes to annotation-object selection changes.
The callback to invoke when the value changes.
A function that removes the listener.
Subscribes to persistent annotation-tool changes.
The callback to invoke when the value changes.
A function that removes the listener.
Registers a listener called whenever the shown document changes — including the automatic reopen after missing-font registration.
The callback to invoke when the value changes.
An unsubscribe function.
Subscribes to changes in the common annotation/form/page-edit history.
The callback to invoke when the value changes.
A function that removes the listener.
Adds Link annotations over the current text selection. The configured annotation-link request handler is opened once, then the chosen target is applied to each selected visual line as one undoable step.
The resulting Promise.
Registers a listener called when isLoading or loadingProgress changes — for a custom loading UI, or to disable controls while a document opens.
The callback to invoke when the value changes.
An unsubscribe function.
Registers a listener called whenever the currentPageNumber changes —
as the user scrolls/zooms and on document load (fires with the new 1-based
page number, or null when no document is shown). The listener is
deduplicated: it fires only when the value actually changes.
The callback to invoke when the value changes.
An unsubscribe function.
Registers a listener for explicit refreshPages and refreshDocument operations. Document replacement is reported separately by addDocumentChangeListener.
The callback to invoke when the value changes.
A function that removes the listener.
Registers a listener called whenever the text selection changes — as the user drags to select, when a word/all is selected programmatically, and when the selection is cleared. The listener receives a PdfTextSelection snapshot; you can also pull the current state via selection at any time.
The listener is not called for no-op updates (e.g. a drag that stays over the same character).
The callback to invoke when the value changes.
An unsubscribe function.
Adds text-markup annotations for the current text selection. One annotation containing the selected visual-line quadpoints is created per page, as one undoable step, then the selection is cleared. No-op without a selection.
This is the common implementation for Highlight, Underline, Squiggly, and
StrikeOut. color and opacity default to the current annotation style.
The subtype value (TextMarkupAnnotationSubtype).
The color value (string).
The opacity value (number).
The ids of the annotations created by this call, in selected-page order. A selection contained on one page normally returns one id; a selection spanning pages can return one id per page. Returns an empty array when there is no current selection or no markup geometry is created.
Registers a listener called whenever the view transform changes — every pan, zoom, fit, resize and animation frame that actually moves the view. The listener takes no argument; pull the new state from currentTransform or zoom.
Like addPageChangeListener this is driven from the paint loop and is deduplicated, so it fires at most once per frame and never for a no-op.
The callback to invoke when the value changes.
An unsubscribe function.
Applies drawing and text style changes to every currently selected annotation as one undoable step. No-op when nothing is selected. Use alongside setAnnotationStyle (which only affects newly drawn annotations).
The style value (Partial).
OptionalhistoryMergeKey: string
The historyMergeKey value (string).
The resulting Promise.
Whether the current text selection can be converted to Link annotations.
Whether the condition is satisfied.
Whether the current selection can be converted to a text-markup annotation.
Whether the condition is satisfied.
Whether the current text selection can be highlighted (has a selection + annotations on).
Whether the condition is satisfied.
Whether an undone annotation, form, or page edit can be redone.
Whether the condition is satisfied.
Whether Ctrl/Cmd+D can repeat the immediately preceding drag duplication.
Whether the condition is satisfied.
Whether an annotation, form, or page edit can be undone.
Whether the condition is satisfied.
Renders a rectangular PDF-page region and encodes it as a browser image. The rectangle uses normal PDF coordinates (points, origin bottom-left).
The 1-based page number.
The rectangle to process.
Options that customize the operation.
The resulting Promise.
Clears all Undo/Redo entries without changing the document.
Clears the current text selection, hides its handles, and repaints.
Clears a preview installed by previewTextMarkupSelection, restoring the normal selection paint. This does not modify the selection or PDF.
Copies the selected annotations to the viewer-local object clipboard.
Whether the documented condition is satisfied.
Copies the current selection to the system clipboard.
Works in non-secure contexts too (a phone hitting a dev server by its LAN
IP over plain HTTP has no navigator.clipboard); the viewer falls back to
a temporary selection and document.execCommand('copy').
true if there was text to copy (and the write was attempted),
false if the selection was empty or the document forbids copying.
Creates a text searcher whose matches are highlighted by this viewer. The previous searcher (if any) is disposed.
The resulting PdfTextSearcher.
Cuts the selected annotations as one undoable delete operation.
The resulting Promise.
Removes every selected annotation as one undoable step.
The resulting Promise.
Tears down the viewer: cancels timers and animation frames, stops auto-scroll/fling, disconnects the resize observer, disposes the searcher, render cache, and document, and removes the canvas. If the viewer created its own engine (no PdfrxViewerOptions.engine was passed), the rendering worker is shut down too. Idempotent.
Converts a document-space point to a view-space point (CSS pixels relative to the viewer canvas's top-left). Inverse of viewToDocumentPoint.
The docPoint value (Offset).
The converted Offset.
Opens the configured target editor for the single selected Link annotation.
The resulting Promise.
Bring a rectangle (PDF page coordinates on the given page) into view, keeping the current zoom. No-op when already visible.
The 1-based page number.
The rectangle to process.
The additional margin.
The fit-page scale: the zoom at which an entire page fits within the viewport; in built-in spread mode this is the scale for the complete row containing that page. Defaults to the current page.
The effective minimum zoom is min(coverScale, fitPageScale).
OptionalpageNumber: number
The 1-based page number.
The resulting number or null.
Scale a page so its height fills the viewport, centered horizontally. Defaults to the current page. This is the "Fit Height" action.
OptionalpageNumber: number
The 1-based page number.
Optionalduration: number
The animation duration in milliseconds.
Fit an entire page within the viewport (both width and height contained). Defaults to the current page. This is the "Fit Page" action.
OptionalpageNumber: number
The 1-based page number.
Optionalduration: number
Animation duration in ms (defaults to
PdfrxViewerOptions.animationDuration); 0 jumps instantly.
Scale a page so its width fills the viewport, aligning its top to the viewport. In odd/even spread mode, fits the complete row containing the page instead. Defaults to the current page.
OptionalpageNumber: number
The 1-based page number.
Optionalduration: number
The animation duration in milliseconds.
Commits an open Text/FreeText editor and waits until its PDF write finishes.
The resulting Promise.
The next zoom stop above zoom on the factor^k grid, clamped.
The zoom factor.
The resolved number.
Hit-tests a view-space point (CSS pixels relative to the canvas, e.g.
from event.offsetX/Y) against the laid-out pages.
The viewPoint value (Offset).
The page under the point and the hit location in PDF page
coordinates, or null if the point is not over any page (in the margin or
background).
The previous zoom stop below zoom on the factor^k grid, clamped.
The zoom factor.
The resolved number.
Client-viewport bounds of the current annotation-object selection, including its visible anchor handles.
The resolved DOMRectReadOnly or null.
The id of the first selected annotation, or null.
The resolved string or null.
The ids of all currently selected annotations.
The resolved string[].
Snapshots of all currently selected annotations that are loaded in the viewer.
The resolved PdfAnnotationObject[].
Navigate to a PDF explicit destination. Falls back to goToPage for
unknown/short-hand destinations.
The dest value (PdfDest or ).
Optionalduration: number
Animation duration in ms (defaults to
PdfrxViewerOptions.animationDuration); 0 jumps instantly.
Navigates to the given page (1-based) without changing zoomMode. In page- or width-fit mode the target page is fitted using the active mode; at an explicit zoom its top edge is shown while preserving that zoom.
The 1-based page number.
Optionalduration: number
Animation duration in ms (defaults to
PdfrxViewerOptions.animationDuration); 0 jumps instantly.
Highlights the current text selection. Compatibility shorthand for
addTextMarkupToSelection('highlight', color, opacity).
The color value (string).
The opacity value (number).
The created Highlight annotation ids in selected-page order, or an empty array when nothing is created.
Whether persistent annotation-object interaction is enabled.
Whether the condition is satisfied.
Whether annotation object interaction is available.
The altOrOptionHeld value (boolean).
Whether the condition is satisfied.
Loads (and caches) the structured text of a page.
The 1-based page number.
The resolved Promise.
Opens a document from in-memory bytes and displays it, replacing any current document. The viewer keeps its own source copy for the missing-font reopen (see openUrl); the supplied buffer is consumed by the engine.
The input data.
Options that customize the operation.
The resolved Promise.
Opens a document by URL and displays it, replacing any current document.
The engine fetches the file, so the URL must be same-origin or CORS-enabled
(relative URLs resolve against document.baseURI). The source is retained
so the viewer can transparently reopen it after registering missing-font
fallbacks. For password-protected PDFs, supply a provider via options.
The URL to use.
Options that customize the operation.
The resolved Promise.
Pastes the object clipboard and selects the newly created annotations. Copy/paste offsets each generation by 10pt; the first paste after a cut retains the original position. A multi-object paste is one undo step.
The resulting Promise.
Prepares browser-dependent resources used by a remotely supplied annotation before it is written to this viewer's document. In particular, FreeText font registrations live in one engine worker and therefore must be repeated independently by every collaboration participant.
The spec value (PdfAnnotationSpec).
The resulting Promise.
Temporarily previews a text-markup style over the current selection without creating or changing a PDF annotation or entering undo history. Call this when a picker candidate is hovered or focused, and call clearTextMarkupSelectionPreview when it is left or the picker closes. The preview remains until cleared or the context menu is dismissed.
Markup geometry to paint.
CSS color used for the temporary fill or stroke.
Preview opacity. Defaults to 0.5 for Highlight and 1
for line-based subtypes.
Render all pages at the given DPI and open the browser print dialog.
Options that customize the operation.
The resulting Promise.
Redoes the next undone annotation, form, or page edit.
The resulting Promise.
Rebuilds every viewer-side representation of the current PdfDocument
without reopening PDFium.
Use this after raw edits to document-level structures (for example the outline, AcroForm, name trees, or page tree), or whenever their exact GUI impact is unknown. All page render/data caches, search state, thumbnails, React document-derived hooks, page overlays, and viewer overlays are refreshed. The current zoom and viewport are retained.
This calls PdfDocument.reloadPages() to recreate page metadata, but it
does not reconstruct the native PDFium document. Use reloadDocument
for that stronger boundary.
The resulting Promise.
Rebuilds all page overlays from PdfrxViewerOptions.pageOverlaysBuilder. Call this after the state your builder depends on has changed.
Invalidates selected viewer caches after low-level edits to the current PDF.
The viewer cannot infer which GUI data a raw dictionary/array/stream edit
affects. Call this method after PdfDocument.editRawObjects() when the
affected pages and cache categories are known. This does not reopen the PDF.
reloadMetadata recreates PDFium page objects before repainting. It is
normally unnecessary for content-stream-only edits, but is appropriate
after changing page dictionaries, dimensions, rotations, or the page tree.
For document-level structures or an unknown impact, use
refreshDocument; if PDFium itself must be reconstructed, use
reloadDocument.
Options that customize the operation.
The resulting Promise.
Re-evaluates permission-dependent overlays and listeners after changing
enforceDocumentPermissions or permissionOverrides at runtime.
Rebuilds the viewport-fixed overlays from PdfrxViewerOptions.viewerOverlayBuilder. Called automatically on resize and document change; call this after your builder's inputs change.
Fully reconstructs the current PDFium document and all viewer state.
The current document is encoded into an independent native copy, which is then installed as the viewer's document; the previous document is disposed. This is the most reliable refresh after arbitrary raw edits, but it copies and reparses the whole PDF, so its time and peak-memory costs grow with document size. Zoom and viewport are retained where the new layout allows.
The resulting Promise.
Render a page thumbnail at the given CSS width.
The 1-based page number.
The width.
The rendered Promise.
Repeats the last modifier-drag duplication using the same displacement.
The resulting Promise.
Select all text of all pages (loads page texts as needed).
The resulting Promise.
Selects every annotation on one page. Defaults to the page occupying the largest visible area, matching currentPageNumber.
The 1-based page number.
The resulting Promise.
Lets the user drag a rectangular page area. Escape or a pointer release outside the starting page cancels. Only one selection can run at a time.
The resulting Promise.
Selects the word at a view-space point (CSS pixels relative to the
canvas), like a double-click. The point's page text must already be loaded
(it is for visible pages). Returns true if a word was selected.
The viewPoint value (Offset).
Whether the documented condition is satisfied.
Installs the UI used to request a target for new or existing Link annotations.
The handler value (AnnotationLinkRequestHandler or ).
Switches between normal viewing/text selection and annotation-object interaction. In annotation mode, left-dragging empty page space performs marquee selection. Alt/Option temporarily inverts the effective mode.
The enabled value (boolean).
Updates the style applied to newly drawn annotations.
The style value (Partial).
Selects a drawing tool, or null for plain object selection in annotation mode.
The tool value (AnnotationTool or ).
Switches the page-layout direction at runtime, re-laying out the document and refitting the view. No-op if unchanged or if a custom PdfrxViewerOptions.layoutPages is in effect (which always wins).
The direction value (LayoutDirection).
Stages the supplied immutable tree as the document's logical outline.
The outline value.
Replaces one page slot and records it as one undoable edit.
The 1-based page number.
The page to process.
Options that customize the operation.
Sets (or clears with null) the page overlays builder and rebuilds
overlays. Convenience for callers that construct the viewer without the
PdfrxViewerOptions.pageOverlaysBuilder option (e.g. the custom element).
The builder value (PageOverlaysBuilder or ).
Replaces the page arrangement and records it as one undoable edit.
The pages to process, in document order.
Options that customize the operation.
Selects (highlights) a single annotation by id, or clears with null.
The id value (string or ).
Replaces the selection with ids and redraws anchor handles.
The ids value (Iterable).
Switches between continuous single-page layout and the two book pairings. Re-lays out and refits the current document.
The mode value (ViewerSpreadMode).
Sets (or restores) the text selection from a PdfTextSelectionRange —
the same shape carried by selection.range, so you can save that
value and pass it back here later. Both endpoint indices are inclusive.
Pass null to clear the selection (equivalent to clearSelection).
Loads the endpoint pages' text as needed (hence async). Indices are clamped
to each page's character range. Returns true if a selection was set, or
false if it could not be (e.g. no document, or the endpoint pages have no
selectable text).
The range value (PdfTextSelectionRange or ).
The resulting Promise.
Sets (or clears with null) the viewport-fixed overlay builder and rebuilds
it. Convenience for callers that construct the viewer without the
PdfrxViewerOptions.viewerOverlayBuilder option.
The builder value (ViewerOverlayBuilder or ).
Applies a zoom and pan together, then waits until every page region in the viewer's logical viewport has been rendered at the viewer's full-quality target and painted to the canvas.
The transform is boundary-clamped in the same way as interactive panning
and zooming. If another view change supersedes this transform while the
promise is pending, it resolves with { status: 'superseded', reason }
rather than reporting completion for a different frame. Rendering failures
are propagated as promise rejections.
Uniform zoom and zoomed document offset to apply.
OptionalsourceViewSize: Size
Explicit viewport size in which transform was
captured. This is only needed for legacy transforms that do not already
contain the snapshot metadata returned by currentTransform.
The completion report for this transform. Actual rendering failures reject the promise.
await viewer.openUrl('/manual.pdf');
await viewer.setViewTransform(savedTransform);
// The saved viewport is now painted at full quality.
currentTransform includes its capture-time viewport size. Saving and passing that snapshot back automatically reproduces the preview's composition when the viewer size has changed. The transform is uniformly scaled and centred in the new view.
Sets the absolute zoom, keeping a view point fixed on screen. The value is
clamped to [minZoom, maxZoom], where the effective minimum is
min(coverScale, fitPageScale) — you can never zoom out
past seeing a whole page — and the maximum is
PdfrxViewerOptions.maxZoom (default 8). To fit a page rather than
pick an absolute factor, use fitToPage / fitToWidth /
fitToHeight.
Target zoom factor (1 = one PDF point per CSS pixel).
OptionalviewCenter: Offset
View-space point to keep stationary. Defaults to the center of the viewport.
Optionalduration: number
Animation duration in ms (defaults to
PdfrxViewerOptions.animationDuration); 0 jumps instantly.
Switches between an explicit zoom factor, fit-page, and fit-width mode. Fit modes are responsive and are recalculated on viewport resize.
The mode value (ZoomMode).
Optionalduration: number
The animation duration in milliseconds.
Undoes the latest annotation, form, or page edit.
The resulting Promise.
Waits until the current transform's logical viewer viewport is rendered at
full quality and painted. Browser-window clipping and ancestor scrolling
do not change this deterministic render target.
Unlike addTransformChangeListener, this includes asynchronous page
bitmap rendering. A later view change resolves with a superseded result;
a page-render failure rejects with that failure. Resolves
immediately when called without a document/layout to render.
The completion report for the captured transform. Actual rendering failures reject the promise.
Toggles between the fit-page zoom and a zoomed-in level
(PdfrxViewerOptions.doubleTapZoomFactor× fit), centered on
viewPoint. This is what touch double-tap and (optionally) mouse
double-click invoke.
OptionalviewPoint: Offset
The viewPoint value (Offset).
Optionalduration: number
The animation duration in milliseconds.
Zooms and pans so a PDF-page rectangle fills the viewport.
The 1-based page number.
The rectangle to process.
Optionalduration: number
The animation duration in milliseconds.
Zooms in to the next zoom stop (factor^k, see
PdfrxViewerOptions.zoomStepFactor), keeping viewCenter fixed.
OptionalviewCenter: Offset
The viewCenter value (Offset).
Optionalduration: number
The animation duration in milliseconds.
Canvas-based PDF viewer: renders pages to a
<canvas>and drives panning, zoom, text selection, links, search, and printing.Constructs a
<canvas>inside the given container, opens a document with openUrl / openData, and drives rendering, panning, pinch zoom, text selection, links, search, and printing. All geometry and selection logic lives in@pdfrx/viewer-core; this class owns the DOM canvas, the pointer state machine, and the render loop. Text selection is painted on the canvas — there is deliberately no DOM text layer.Always call dispose when done; if the viewer created its own engine, disposal also tears down the rendering worker.
Example