Interface PdfrxViewerOptions

Fill style for the active (current) search-match highlight. Default: 'rgba(255, 152, 0, 0.5)'.

Default animation duration in milliseconds for navigation and zoom (goToPage, goToDest, fitTo*, setZoom, zoomUp/zoomDown, zoomToggle). 0 (the default) means jump instantly. Each of those methods also takes a per-call duration that overrides this.

Text shown by annotation text-editing UI. Defaults to { text: 'Text', note: 'Note' }; localized UI wrappers can override it.

Detect URL-like page text that is not backed by a PDF Link annotation and make it clickable in viewing interactions. Detected links are transient: they are not returned by annotation APIs and cannot be edited, persisted, synchronized, or exported. Default: true.

CSS background color of the viewer. Default: '#808080'. Alpha colors such as 'rgba(0, 0, 0, 0.5)' and 'transparent' reveal the content behind the viewer.

Extra scrollable margin, in document units, added around the document so it can be panned past its edges. Default: 0 (edges are hard boundaries).

Replaces the built-in right-click / long-press context menu (which offers Copy, Highlight, Add link, and Select All in English). Return a menu element the viewer will position and dismiss, or null/undefined for no menu. This is the hook for localizing or fully customizing the menu — the viewer itself carries no translation machinery. See ContextMenuBuilder.

Make a mouse double-click zoom (via PdfrxViewer.zoomToggle) instead of selecting the word under the cursor. Off by default (double-click selects a word, the common text-viewer behavior).

Enables touch double-tap to zoom in/out at the tapped point (animated with animationDuration or a 250 ms default). On by default.

How far PdfrxViewer.zoomToggle (and double-tap, when enabled) zooms in, as a multiple of the fit-page scale. Default: 3.

Fine-grained editing policy. All capabilities default to enabled.

Respect the PDF permission flags in standard viewer interactions. Default: true. These flags are advisory, not cryptographic security.

Engine to use. If omitted, the viewer creates and owns one from engineOptions and disposes it on PdfrxViewer.dispose. Pass a shared engine to open several viewers against one worker; then the caller owns its lifetime.

Options for the engine created when engine is not supplied. Its wasmModulesUrl must point at a directory containing pdfium_worker.js and pdfium.wasm. Defaults to { wasmModulesUrl: 'pdfium/' }.

Resolver for fonts the PDF does not embed. Defaults to the Google Fonts resolver (downloads from fonts.gstatic.com); pass null to disable.

Preferred language for ambiguous CJK FreeText (notably Han-only text). Accepts BCP-47 tags in priority order. When omitted, the browser's navigator.languages is used. Explicit kana/Hangul still take precedence. The resolved font runs are persisted with the annotation.

Selection handle color (touch). Default: '#2196f3'.

How the first page is fitted into the viewport when a document loads. 'page' and 'width' become persistent responsive zoom modes and are recalculated on viewport resize. 'height' is retained as a one-time initial fit and then behaves as an explicit numeric zoom. See PdfrxViewer.fitToPage.

• 'page' (default) — the whole first page fits within the viewport.
• 'width' — the first page's width fills the viewport (top-aligned).
• 'height' — the first page's height fills the viewport.

Paints page annotations (ink, shapes, text markup, notes) through an SVG overlay instead of the canvas, and enables in-viewer annotation editing via PdfrxViewer.setAnnotationTool. While on, the canvas renders form widgets but not annotations (they come from the overlay), so per-edit updates never re-render the page — no flicker. Edits are written back to the PDF and reflected by PdfDocument.encodePdf. Default: true.

Overlays native HTML controls over AcroForm fields so the user can fill the form (text inputs, checkboxes, radios, dropdowns). Edits are written back to the owning source PDF and reflected when that document is encoded. Exporting one virtual arrangement made from several source PDFs requires an application-level AcroForm catalog merge. Default: true.

Direction pages are laid out and scrolled: 'vertical' (default, stacked top-to-bottom) or 'horizontal' (side-by-side). In horizontal mode a plain mouse wheel scrolls sideways through the pages. Ignored when layoutPages is set. Can also be changed at runtime with PdfrxViewer.setLayoutDirection.

Custom page-layout function, for facing/two-up/grid arrangements. Given the page geometries and the resolved margin, return each page's rect (document coordinates, y-down) and the total document size. When set, it fully replaces the built-in vertical/horizontal layouts (so layoutDirection is ignored). See LayoutPagesFn.

Paint a spinner (and a progress bar, when the byte count is known) while a document is opening, instead of leaving the previous one on screen. Set to false to draw your own from PdfrxViewer.isLoading / PdfrxViewer.addLoadingChangeListener — the previous document is hidden either way. Default: true.

Color of the built-in loading indicator. Default: 'rgba(255, 255, 255, 0.85)'.

Margin around/between pages in document units. Default: 8.

Fill style for search-match highlights. Default: 'rgba(255, 235, 59, 0.5)'.

Maximum zoom. Default: 8.

Minimum zoom. When omitted, it is computed dynamically as min(PdfrxViewer.coverScale, PdfrxViewer.fitPageScale) for the current page, so you can never zoom out past seeing a whole page. Set an explicit number to override that behavior.

Called for discrete pointer gestures — single tap, double-tap, long-press, and secondary (right/two-finger) tap — with the type and view-space point. Fires in addition to the viewer's own handling (selection, links, zoom).

Called when the current gesture ends and the viewer returns to idle.

Called when a gesture (pan/pinch/select/handle-drag) begins. Pair with onInteractionEnd to e.g. pause other work while the user interacts.

Called when the user taps/clicks a link. When provided, it replaces the built-in behavior (open external URLs with window.open, navigate internal destinations with PdfrxViewer.goToDest). Use PdfLink.target to decide, and call PdfrxViewer.goToDest / window.open yourself to keep parts of the default. Omit it to keep the built-in behavior.

Called once a document has loaded and the viewer is laid out and ready to interact with (after the initial fit). Fires again whenever a new document is opened.

Called when the viewport size changes (element resize), with the new size in CSS pixels. Not called for the initial layout.

Custom painters invoked behind each page, before the page background is filled — useful for custom shadows or backdrops that extend outside the page. Each callback receives the canvas already transformed to document coordinates and the page's document-space rect.

Border drawn around every page (in screen space). Off by default; set a PageBorder to enable it.

Drop shadow drawn behind every page (in screen space, so it looks the same at any zoom). Defaults to a soft shadow; pass null to remove it. See PageDropShadow.

Builds DOM overlays laid over each page. The returned elements are placed in a per-page layer that is translated and scaled to follow the page, so they pan and zoom together with it. Position the elements in page-point coordinates (origin at the page's top-left, one unit = one PDF point at zoom 1); the viewer applies the zoom scale. See PageOverlaysBuilder.

The overlay layer is click-through by default; give an element pointerEvents: 'auto' to make it interactive. Built lazily per visible page — cheap for large documents. Call PdfrxViewer.refreshOverlays to rebuild after external state changes.

Custom painters invoked on top of each page's rendered content — useful for watermarks, page numbers, or custom borders. Same coordinate space as pageBackgroundPaintCallbacks.

Restricts primary-button and touch drag-panning to one axis. 'free' (default) pans in both; 'horizontal' / 'vertical' lock to that axis; 'aligned' locks each pan gesture to whichever axis it starts moving along. Wheel/keyboard scrolling and programmatic navigation are unaffected.

Enables drag-to-pan (primary-button background drag or touch drag). In annotation mode, primary drag instead manipulates an object/anchor or marquee-selects from empty page space. Default: true.

Application overrides applied before PDF permission flags.

Enables arrow-key / Page/Home/End scrolling. Default: true.

Enables mouse-wheel / trackpad scrolling. Default: true.

Selection highlight fill style. Default: 'rgba(33, 150, 243, 0.35)'.

Built-in two-page book layout. 'odd' pairs pages 1–2, 3–4; 'even' leaves page 1 alone and pairs 2–3, 4–5. Default: 'none'. Ignored when layoutPages is set.

Overrides environment-dependent FreeText measurement, font resolution, or emoji rendering. The viewer supplies browser defaults and delegates the shared grapheme/language/layout logic to @pdfrx/engine.

Compositing mode used for text selection, search matches, highlight annotations, and hovered links. Defaults to 'multiply', which tints light page backgrounds while keeping dark text dark. Use 'normal' to restore conventional alpha overlay painting, for example on predominantly dark pages.

Builds DOM overlays fixed to the viewport (they do not pan or zoom with the pages) — for scroll thumbs, floating toolbars, page badges, etc. The layer sits above the canvas and is click-through unless a child sets pointerEvents: 'auto'. Rebuilt on resize and document change; call PdfrxViewer.refreshViewerOverlays to rebuild on demand.

Enables gesture zoom (pinch and ctrl/cmd + wheel). When disabled, a two-finger gesture can still pan if panEnabled is enabled. Programmatic zoom is unaffected. Default: true.

Multiplicative step between zoom stops for PdfrxViewer.zoomUp / PdfrxViewer.zoomDown (and ctrl/cmd +/-). Stops are factor^k, so repeated up/down lands on the same grid. Default: √2.