pdfrx_web
    Preparing search index...

    Interface PdfrxProviderProps

    Props for PdfrxProvider.

    interface PdfrxProviderProps {
        activeMatchTextColor?: string;
        animationDuration?: number;
        annotationEditorPlaceholders?: { note?: string; text?: string };
        autoLinkDetection?: boolean;
        backgroundColor?: string;
        boundaryMargin?: number;
        children?: ReactNode;
        contextMenuBuilder?: PdfReactContextMenuBuilder;
        doubleClickToZoom?: boolean;
        doubleTapToZoom?: boolean;
        doubleTapZoomFactor?: number;
        editing?: {
            actorId?: string;
            annotations?: boolean;
            history?: boolean;
            pages?: boolean;
        };
        enforceDocumentPermissions?: boolean;
        engine?: PdfrxEngine;
        engineOptions?: PdfrxEngineOptions;
        fontResolver?: FontResolver
        | null;
        freeTextLanguage?: string | readonly string[];
        handleColor?: string;
        imageDecoder?: PdfImageDecoder;
        initialFit?: FitMode;
        interactiveAnnotations?: boolean;
        interactiveForms?: boolean;
        layoutDirection?: LayoutDirection;
        layoutPages?: LayoutPagesFn;
        loadingIndicator?: boolean;
        loadingIndicatorColor?: string;
        locale?: string | readonly string[];
        margin?: number;
        matchTextColor?: string;
        maxZoom?: number;
        minZoom?: number;
        onError?: (error: unknown) => void;
        onGeneralTap?: (event: PdfViewerTapEvent) => void;
        onInteractionEnd?: () => void;
        onInteractionStart?: () => void;
        onLinkTap?: LinkTapHandler;
        onViewerReady?: () => void;
        onViewSizeChanged?: (viewSize: Size) => void;
        pageBackgroundPaintCallbacks?: PagePaintCallback[];
        pageBorder?: PageBorder | null;
        pageDropShadow?: PageDropShadow | null;
        pageOverlaysBuilder?: PageOverlaysBuilder;
        pagePaintCallbacks?: PagePaintCallback[];
        panAxis?: PanAxis;
        panEnabled?: boolean;
        passwordProvider?: PdfPasswordProvider;
        permissionOverrides?: PdfViewerPermissionOverrides;
        scrollByArrowKey?: boolean;
        scrollByMouseWheel?: boolean;
        selectionColor?: string;
        spreadMode?: ViewerSpreadMode;
        src?: PdfSource;
        strings?: Partial<PdfrxStrings>;
        textAppearanceServices?: PdfTextAppearanceServices;
        textHighlightBlendMode?: "multiply" | "normal";
        viewerOverlayBuilder?: ViewerOverlayBuilder;
        wasmModulesUrl?: string;
        zoomEnabled?: boolean;
        zoomStepFactor?: number;
    }

    Hierarchy (View Summary)

    Index
    activeMatchTextColor? animationDuration? annotationEditorPlaceholders? autoLinkDetection? backgroundColor? boundaryMargin? children? contextMenuBuilder? doubleClickToZoom? doubleTapToZoom? doubleTapZoomFactor? editing? enforceDocumentPermissions? engine? engineOptions? fontResolver? freeTextLanguage? handleColor? imageDecoder? initialFit? interactiveAnnotations? interactiveForms? layoutDirection? layoutPages? loadingIndicator? loadingIndicatorColor? locale? margin? matchTextColor? maxZoom? minZoom? onError? onGeneralTap? onInteractionEnd? onInteractionStart? onLinkTap? onViewerReady? onViewSizeChanged? pageBackgroundPaintCallbacks? pageBorder? pageDropShadow? pageOverlaysBuilder? pagePaintCallbacks? panAxis? panEnabled? passwordProvider? permissionOverrides? scrollByArrowKey? scrollByMouseWheel? selectionColor? spreadMode? src? strings? textAppearanceServices? textHighlightBlendMode? viewerOverlayBuilder? wasmModulesUrl? zoomEnabled? zoomStepFactor?
    activeMatchTextColor?: string

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

    animationDuration?: number

    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.

    annotationEditorPlaceholders?: { note?: string; text?: string }

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

    autoLinkDetection?: boolean

    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.

    backgroundColor?: string

    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.

    boundaryMargin?: number

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

    children?: ReactNode
    contextMenuBuilder?: PdfReactContextMenuBuilder

    Replaces the right-click / long-press context menu. Receives the viewer and active strings alongside the event context, so you can reuse buildDefaultContextMenu and add your own items. Omit it for the built-in localized Copy / Select All menu. See PdfReactContextMenuBuilder.

    doubleClickToZoom?: boolean

    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).

    doubleTapToZoom?: boolean

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

    doubleTapZoomFactor?: number

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

    editing?: {
        actorId?: string;
        annotations?: boolean;
        history?: boolean;
        pages?: boolean;
    }

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

    Type Declaration

    • OptionalactorId?: string

      Stable application/user id attached to viewer-owned mutations.

    • Optionalannotations?: boolean

      Allow annotation creation and modification.

    • Optionalhistory?: boolean

      Record and expose Undo/Redo history.

    • Optionalpages?: boolean

      Allow page rotation, insertion, deletion and reordering through the viewer API.

    enforceDocumentPermissions?: boolean

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

    engine?: PdfrxEngine

    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.

    engineOptions?: PdfrxEngineOptions

    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/' }.

    fontResolver?: FontResolver | null

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

    Missing-font fallback — how the default resolver picks substitutes, and how to customize it.

    freeTextLanguage?: string | readonly string[]

    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.

    handleColor?: string

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

    imageDecoder?: PdfImageDecoder

    Decodes image formats unsupported by the browser, for every built-in image path: opening an image, inserting it as a page, and adding an image stamp. Without this prop, encoded formats unsupported by the current browser (such as HEIC in Chrome) cannot be imported as pages or annotations. Applications can add support without changing pdfrx by converting them to JPEG/PNG or decoded RGBA8888/BGRA8888 pixels here. Return JPEG/PNG/etc. encoded data or decoded RGBA/BGRA pixels. See PdfImageDecoder for a HEIC example.

    initialFit?: FitMode

    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.
    interactiveAnnotations?: boolean

    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.

    interactiveForms?: boolean

    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.

    layoutDirection?: LayoutDirection

    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.

    layoutPages?: LayoutPagesFn

    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.

    loadingIndicator?: boolean

    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.

    loadingIndicatorColor?: string

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

    locale?: string | readonly string[]

    UI language for the built-in components. A BCP-47 tag (or a priority list), matched against the built-in languages (English, Japanese, Simplified and Traditional Chinese, French, German), with English as the fallback. Omit it to auto-detect from the browser (navigator.languages). See resolvePdfrxStrings.

    margin?: number

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

    matchTextColor?: string

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

    maxZoom?: number

    Maximum zoom. Default: 8.

    minZoom?: number

    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.

    onError?: (error: unknown) => void

    Called when opening src fails. The error is also available from usePdfDocument().

    onGeneralTap?: (event: PdfViewerTapEvent) => void

    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).

    onInteractionEnd?: () => void

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

    onInteractionStart?: () => void

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

    onLinkTap?: LinkTapHandler

    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.

    onViewerReady?: () => void

    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.

    onViewSizeChanged?: (viewSize: Size) => void

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

    pageBackgroundPaintCallbacks?: PagePaintCallback[]

    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.

    pageBorder?: PageBorder | null

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

    pageDropShadow?: PageDropShadow | null

    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.

    pageOverlaysBuilder?: PageOverlaysBuilder

    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.

    pagePaintCallbacks?: PagePaintCallback[]

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

    panAxis?: PanAxis

    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.

    panEnabled?: boolean

    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.

    passwordProvider?: PdfPasswordProvider

    Supplies passwords for encrypted documents, applied to every built-in open (the src prop, the file-open button, page insertion) whose source does not carry its own. Called again on each wrong password until it returns a correct one or null (which aborts). See PdfPasswordProvider.

    PdfrxProvider has no default — omit it and encrypted documents fail to open. PdfrxViewerApp installs a localized window.prompt fallback unless you pass one here.

    <PdfrxProvider src="/secret.pdf" passwordProvider={() => prompt('Password:')} />
    permissionOverrides?: PdfViewerPermissionOverrides

    Application overrides applied before PDF permission flags.

    scrollByArrowKey?: boolean

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

    scrollByMouseWheel?: boolean

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

    selectionColor?: string

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

    spreadMode?: ViewerSpreadMode

    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.

    src?: PdfSource

    The document to show. A URL string is the common case; see PdfSource for the byte-array, File and options-carrying forms. Changing it opens the new document; an equivalent value is ignored, so an inline literal is safe.

    strings?: Partial<PdfrxStrings>

    Per-string overrides applied on top of locale — for tweaking a few labels, or supplying a language the package doesn't ship (set locale to it and provide the strings here; anything omitted falls back to English). See PdfrxStrings. Pass a stable (module-level or memoized) object.

    textAppearanceServices?: PdfTextAppearanceServices

    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.

    textHighlightBlendMode?: "multiply" | "normal"

    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.

    viewerOverlayBuilder?: ViewerOverlayBuilder

    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.

    wasmModulesUrl?: string

    Shorthand for engineOptions.wasmModulesUrl — the directory holding pdfium_worker.js and pdfium.wasm. Defaults to 'pdfium/'.

    zoomEnabled?: boolean

    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.

    zoomStepFactor?: number

    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.

    Settings
    Member Visibility

    On This Page
    Properties
    activeMatchTextColoranimationDurationannotationEditorPlaceholdersautoLinkDetectionbackgroundColorboundaryMarginchildrencontextMenuBuilderdoubleClickToZoomdoubleTapToZoomdoubleTapZoomFactoreditingenforceDocumentPermissionsengineengineOptionsfontResolverfreeTextLanguagehandleColorimageDecoderinitialFitinteractiveAnnotationsinteractiveFormslayoutDirectionlayoutPagesloadingIndicatorloadingIndicatorColorlocalemarginmatchTextColormaxZoomminZoomonErroronGeneralTaponInteractionEndonInteractionStartonLinkTaponViewerReadyonViewSizeChangedpageBackgroundPaintCallbackspageBorderpageDropShadowpageOverlaysBuilderpagePaintCallbackspanAxispanEnabledpasswordProviderpermissionOverridesscrollByArrowKeyscrollByMouseWheelselectionColorspreadModesrcstringstextAppearanceServicestextHighlightBlendModeviewerOverlayBuilderwasmModulesUrlzoomEnabledzoomStepFactor