Skip to main content
Version: Version 5

Migrate from version 4 to version 5

This guide helps you migrate from PDF Viewer SDK version 4 to version 5.

PDF Viewer SDK version 5 is a complete rewrite with a different architecture, API, and package structure. The version 5 architecture introduces two packages:

  • PDF Web Viewer: A ready-to-use viewer built around PDF Web SDK.
  • PDF Web SDK: A lower-level SDK for building custom viewers.

This guide covers migrating from version 4 to PDF Web Viewer, the direct replacement for the version 4 package.

Prerequisites​

Before migrating, make sure your environment meets the following requirements:

  • Node.js 18 or later
  • npm 8 or later
  • A modern browser supporting WebAssembly

Installation changes​

Version 5 introduces a new package name, updated import paths, and a renamed static assets directory. Update your package.json, import statements, and build configuration accordingly.

Package name​

The npm package name changed from @pdftools/four-heights-pdf-web-viewer to @pdftools/pdf-web-viewer.

npm install @pdftools/pdf-web-viewer

Import statement​

Update your import statements to use the new package name.

import { PdfToolsViewer } from "@pdftools/pdf-web-viewer";

Static assets directory​

The static assets directory changed from pdfwebviewer to pdftools-web-viewer.

node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer/

Update your build configuration to copy assets from the new location.

Webpack​

For Webpack, update the CopyWebpackPlugin configuration.

new CopyWebpackPlugin({
  patterns: [
    {
      from: "node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer",
      to: "pdftools-web-viewer",
    },
  ],
});

Angular​

For Angular, update the assets array in angular.json.

{
  "glob": "**/*",
  "input": "node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer",
  "output": "/pdftools-web-viewer/"
}

Rollup​

For Rollup, update the rollup-plugin-copy targets.

copy({
  targets: [
    {
      src: "node_modules/@pdftools/pdf-web-viewer/pdftools-web-viewer",
      dest: "pdftools-web-viewer",
    },
  ],
});

Initialization​

In version 4, you initialized the viewer through a constructor and a global base URL. In version 5, you create an instance, then call the async initialize() method.

Update the viewer initialization​

Replace the version 4 constructor with a version 5 instance and an initialize() call.

import { PdfToolsViewer } from "@pdftools/pdf-web-viewer";

async function init() {
  // Create viewer instance
  const viewer = new PdfToolsViewer();
  // Get container element
  const container = document.getElementById("pdftools-viewer-container");

  // Initialize the viewer
  await viewer.initialize(
    {
      licenseKey: "YOUR_LICENSE_KEY",
      user: "John Doe",
      locale: "en",
    },
    container
  );
}

init();

Besides licenseKey, user, and locale, the initialize() method accepts many more configuration options. For the full list, refer to ViewerConfig in the PDF Viewer SDK API reference.

License​

Two options are available to configure the license:

  • licenseKey: Your license identifier. Required for PDF Web Viewer to function.
  • licenseUrl: URL of the Licensing Gateway Service for online validation. Defaults to https://licensing.pdf-tools.com/api/v1/viewer/licenses/.
await viewer.initialize(
  {
    licenseKey: "YOUR_LICENSE_KEY",
    licenseUrl: "https://your-gateway.com/api/licenses/", // Optional
  },
  container
);
note

If you’re using a trial license, PDF Web Viewer adds a watermark to documents.

Asset path​

In version 4, you had to set a global variable before loading PDF Web Viewer:

<script type="text/javascript">
  window.PDFTOOLS_FOURHEIGHTS_PDFVIEWING_BASEURL = "./pdfwebviewer/";
</script>

Remove this script tag. In version 5, the viewer automatically resolves the asset path. If you serve assets from a custom location, specify it in the initialize() options:

await viewer.initialize(
  {
    path: "./custom-path/pdftools-web-viewer/",
  },
  container
);

The path option tells PDF Web Viewer where to find its worker script and assets. Set this to match the destination in your build configuration.

General options​

In version 4, you configured general viewer settings through the viewer.general object. In version 5, pass these options directly to the initialize() method or use runtime methods to read and update them.

User​

Sets the current user name for annotations and comments.

In version 4, you set the user through the viewer.general.user option in the configuration object.

In version 5, pass the user option to the initialize() method. You can also read and update the user at runtime using the getUser() and setUser() methods.

await viewer.initialize({ user: "John Doe" }, container);

// Read the current user
const currentUser = viewer.getUser();

// Update the user at runtime
viewer.setUser("Jane Doe");

Locale​

Sets the UI language.

In version 4, you set the language through the viewer.general.language option in the configuration object.

In version 5, pass the locale option to the initialize() method. You can set a specific locale code (for example, "en", "de", "fr") or use "auto" for automatic browser detection.

Version 5 also provides runtime methods for locales:

// Set a specific locale
await viewer.initialize({ locale: "de" }, container);

// Or use automatic browser detection
await viewer.initialize({ locale: "auto" }, container);

// Update the locale at runtime
viewer.setLocale("fr");

Prompt on unsaved change​

Shows a confirmation dialog when the user tries to close or navigate away from a document with unsaved changes.

In version 4, you set this through the viewer.general.promptOnUnsavedChange option in the configuration object.

In version 5, pass the promptOnUnsavedChange option to the initialize() method.

await viewer.initialize({ promptOnUnsavedChange: true }, container);

Hide password dialog cancel button​

Hides the cancel button in the password dialog, forcing users to enter a password to proceed.

In version 4, you set this through the viewer.general.hidePasswordFormCancelButton option in the configuration object.

In version 5, pass the hidePasswordDialogCancelButton option to the initialize() method.

await viewer.initialize({ hidePasswordDialogCancelButton: true }, container);

Disable main toolbar​

Hides the main toolbar at the top of the viewer.

In version 4, you set this through the viewer.general.disableMainToolbar option in the configuration object.

In version 5, use the hideComponents() method after initialization. To show it again, use showComponents().

await viewer.initialize({}, container);

// Hide the toolbar
viewer.hideComponents("toolbar");

// Show it again
viewer.showComponents("toolbar");

Disable annotation toolbar​

Hides the annotation toolbar.

In version 4, you set this through the viewer.general.disableAnnotationToolbar option in the configuration object.

In version 5, use the hideComponents() method after initialization. To show it again, use showComponents().

await viewer.initialize({}, container);

// Hide the annotation toolbar
viewer.hideComponents("annotation-toolbar");

// Show it again
viewer.showComponents("annotation-toolbar");

In version 5, you control sidebar panels using the hideComponents() and showComponents() methods instead of configuration options.

Thumbnail navigation​

Shows or hides the thumbnails panel and button in the sidebar.

In version 4, you set this through the viewer.sidebar.thumbnailNavigation option in the configuration object.

In version 5, use the hideComponents() method after initialization.

await viewer.initialize({}, container);

// Hide the thumbnails panel and button
viewer.hideComponents(["thumbnails-panel", "thumbnails-button"]);

Outline navigation​

Shows or hides the document outline (bookmarks) panel and button in the sidebar.

In version 4, you set this through the viewer.sidebar.outlineNavigation option in the configuration object.

In version 5, use the hideComponents() method after initialization.

await viewer.initialize({}, container);

// Hide the outline panel and button
viewer.hideComponents(["overview-panel", "overview-button"]);

Annotation navigation​

Shows or hides the annotations panel and button in the sidebar.

In version 4, you set this through the viewer.sidebar.annotationNavigation option in the configuration object.

In version 5, use the hideComponents() method after initialization.

await viewer.initialize({}, container);

// Hide the annotations panel and button
viewer.hideComponents(["annotations-panel", "annotations-button"]);

Permission options​

In version 4, permission options controlled which features users could access. Version 5 doesn’t yet implement most of these options. For the full list, refer to Features not supported in version 5. The following options are available:

Enable page layout mode​

Shows or hides the page layout mode dropdown.

In version 4, you set this through the viewer.permissions.enablePageLayoutMode option in the configuration object.

In version 5, use the hideComponents() method after initialization.

await viewer.initialize({}, container);

// Hide the page mode dropdown
viewer.hideComponents("page-mode-dropdown");

Shows or hides the search feature.

In version 4, you set this through the viewer.permissions.enableSearch option in the configuration object.

In version 5, use the hideComponents() method after initialization.

await viewer.initialize({}, container);

// Hide the search button and panel
viewer.hideComponents(["search-button", "search-panel"]);

Zoom levels​

Defines the available zoom levels in the zoom dropdown.

In version 4, you set this through the viewer.general.defaultZoomLevels option in the configuration object.

In version 5, pass the zoomLevels option to the initialize() method.

await viewer.initialize(
  {
    zoomLevels: [25, 50, 75, 100, 150, 200],
  },
  container
);

Events​

Version 5 uses a different event system, with namespaced event names and separate event targets. Version 5 doesn’t yet support some events. See Features not supported in version 5.

App loaded​

Fired when PDF Web Viewer finishes initializing and is ready.

In version 4, listen for the appLoaded event on the viewer instance.

In version 5, listen for the PdfTools.viewer.initialized event on the viewer object. See EventMap for all viewer events.

viewer.addEventListener("PdfTools.viewer.initialized", () => {
  console.log("Viewer ready");
});

Document loaded​

Fired when a document opens.

In version 4, listen for the documentLoaded event on the viewer instance.

In version 5, listen for the PdfTools.document.opened event on the viewer object. See EventMap for all viewer events. You can also use the short form opened on viewer.document. See DocumentEventMap for all document events.

// Using the full event name on viewer
viewer.addEventListener("PdfTools.document.opened", (inputDocument) => {
  console.log("Document opened:", inputDocument);
});

// Or using the short form on viewer.document
viewer.document.addEventListener("opened", (inputDocument) => {
  console.log("Document opened:", inputDocument);
});

Document changed​

Fired when the document changes.

In version 4, listen for the documentChanged event on the viewer instance.

In version 5, listen for the PdfTools.document.changed event on the viewer object. See EventMap for all viewer events. You can also use the short form changed on viewer.document. See DocumentEventMap for all document events.

// Using the full event name on viewer
viewer.addEventListener("PdfTools.document.changed", () => {
  console.log("Document changed");
});

// Or using the short form on viewer.document
viewer.document.addEventListener("changed", () => {
  console.log("Document changed");
});

Page number changed​

Fired when the current page changes.

In version 4, listen for the pageNumberChanged event on the viewer instance.

In version 5, listen for the PdfTools.documentView.pageChanged event on the viewer object. See EventMap for all viewer events. You can also use the short form pageChanged on viewer.documentView. See DocumentViewEventMap for all document view events.

// Using the full event name on viewer
viewer.addEventListener("PdfTools.documentView.pageChanged", (pageNumber) => {
  console.log("Current page:", pageNumber);
});

// Or using the short form on viewer.documentView
viewer.documentView.addEventListener("pageChanged", (pageNumber) => {
  console.log("Current page:", pageNumber);
});

Zoom changed​

Fired when the zoom level changes.

In version 4, listen for the zoomChanged event on the viewer instance.

In version 5, listen for the PdfTools.documentView.zoomChanged event on the viewer object. See EventMap for all viewer events. You can also use the short form zoomChanged on viewer.documentView. See DocumentViewEventMap for all document view events.

// Using the full event name on viewer
viewer.addEventListener("PdfTools.documentView.zoomChanged", (zoom) => {
  console.log("Zoom level:", zoom);
});

// Or using the short form on viewer.documentView
viewer.documentView.addEventListener("zoomChanged", (zoom) => {
  console.log("Zoom level:", zoom);
});

Rotation changed​

Fired when a page rotates.

In version 4, listen for the rotationChanged event on the viewer instance.

In version 5, listen for the PdfTools.document.pageRotated event on the viewer object. See EventMap for all viewer events. You can also use the short form pageRotated on viewer.document. See DocumentEventMap for all document events.

// Using the full event name on viewer
viewer.addEventListener("PdfTools.document.pageRotated", (pageNumber, rotation) => {
  console.log(`Page ${pageNumber} rotation:`, rotation);
});

// Or using the short form on viewer.document
viewer.document.addEventListener("pageRotated", (pageNumber, rotation) => {
  console.log(`Page ${pageNumber} rotation:`, rotation);
});

Fit mode changed​

Fired when the fit mode changes, such as fit to page or fit to width.

In version 4, listen for the fitModeChanged event on the viewer instance.

In version 5, listen for the PdfTools.documentView.fitModeChanged event on the viewer object. See EventMap for all viewer events. You can also use the short form fitModeChanged on viewer.documentView. See DocumentViewEventMap for all document view events.

// Using the full event name on viewer
viewer.addEventListener("PdfTools.documentView.fitModeChanged", (fitMode) => {
  console.log("Fit mode:", fitMode);
});

// Or using the short form on viewer.documentView
viewer.documentView.addEventListener("fitModeChanged", (fitMode) => {
  console.log("Fit mode:", fitMode);
});

Page layout mode changed​

Fired when the page layout mode changes, such as single page or continuous.

In version 4, listen for the pageLayoutModeChanged event on the viewer instance.

In version 5, listen for the PdfTools.documentView.pageModeChanged event on the viewer object. See EventMap for all viewer events. You can also use the short form pageModeChanged on viewer.documentView. See DocumentViewEventMap for all document view events.

// Using the full event name on viewer
viewer.addEventListener("PdfTools.documentView.pageModeChanged", (pageMode) => {
  console.log("Page mode:", pageMode);
});

// Or using the short form on viewer.documentView
viewer.documentView.addEventListener("pageModeChanged", (pageMode) => {
  console.log("Page mode:", pageMode);
});

Callbacks​

In version 4, you configured callbacks through the callbacks option in the configuration object.

In version 5, use the overrideButtonBehavior() method to customize button behavior.

Open file button clicked​

Triggered when the user clicks the open file button.

In version 4, set the callbacks.onOpenFileButtonClicked option in the configuration object.

In version 5, use the overrideButtonBehavior() method with open-document-button.

viewer.overrideButtonBehavior("open-document-button", "click", () => {
  // Custom open logic
});

Save file button clicked​

Triggered when the user clicks the save file button.

In version 4, set the callbacks.onSaveFileButtonClicked option in the configuration object.

In version 5, use the overrideButtonBehavior() method with save-button.

viewer.overrideButtonBehavior("save-button", "click", async () => {
  // Custom save logic
  await viewer.document.save({ saveOriginal: true });
});

Custom buttons​

Adds custom buttons to the PDF Web Viewer toolbars.

In version 4, you added custom buttons through the customButtons.documentbar, customButtons.informationbar, and customButtons.annotationbar options in the configuration object.

In version 5, PDF Web Viewer doesn’t support these options directly. Instead, create your own UI elements with HTML and JavaScript, and call the PDF Web Viewer API from them.

await viewer.initialize({}, container);

// Create custom UI elements using HTML/JavaScript
const button = document.createElement("button");
button.textContent = "My Button";
button.addEventListener("click", () => {
    // Add custom logic and call the viewer API.
});

Modules​

Extends PDF Web Viewer with custom features.

In version 4, you registered custom modules through the modules option in the configuration object.

In version 5, use the plugins API to register and manage plugins. See the Custom plugins guide for details.

await viewer.initialize({}, container);

// Register a custom plugin
viewer.plugins.register(myCustomPlugin);

// Deregister a plugin
viewer.plugins.deregister("my-plugin-id");

Forms​

Enables interactive form filling in PDF documents.

In version 4, you configured form filling through the viewer.forms option in the configuration object.

In version 5, PDF Web Viewer enables form filling by default. To disable it, deregister the edit-widget-annotation-plugin using the plugins API.

// Form filling is enabled by default
await viewer.initialize({}, container);

// To disable form filling
viewer.plugins.deregister("edit-widget-annotation-plugin");

Features not supported in version 5​

The following features of PDF Viewer SDK version 4 aren’t supported in version 5.

General options​

Version 5 doesn’t support the following general options:

  • annotationBarPosition: Annotation toolbar position configuration
  • searchMatchColor: Search match highlight color
  • textSelectionColor: Text selection highlight color
  • rectangularTextSelection: Rectangular text selection mode
  • pageShadow: Page shadow styling
  • currentPageShadow: Current page shadow styling
  • tooltips: Tooltip configuration
  • viewOnly: View-only mode (annotations disabled)

Version 5 doesn’t support the selectedNavigation option for the default sidebar panel selection.

Permission options​

Version 5 doesn’t support the following permission options:

  • allowFileDrop: Drag-and-drop file opening
  • allowSaveFile: Save button visibility
  • allowOpenFile: Open button visibility
  • allowCloseFile: Close button visibility
  • allowRotatePages: Page rotation permission
  • allowRotateView: View rotation permission
  • allowCopyText: Text copy permission
  • allowLockAnnotations: Annotation locking permission
  • allowEditLockedAnnotations: Locked annotation editing
  • allowPrinting: Print permission
  • allowExternalLinks: External link handling

Annotation options​

Version 5 doesn’t support the following annotation options:

  • pdfStampFiles: PDF files for stamp annotations
  • stamps: Stamp annotation configuration
  • colors: Annotation color options
  • fonts: Annotation font options
  • highlightOpacity: Highlight annotation opacity
  • strokeWidths: Stroke width options
  • defaultBorderWidth: Default annotation border width
  • defaultStampWidth: Default stamp annotation width
  • eraserRadius: Ink annotation eraser radius
  • selectedStamp: Default selected stamp
  • hideAnnotationSubject: Annotation subject visibility
  • trackHistory: Annotation history tracking
  • hideOnDelete: Hide annotations instead of deleting
  • onlyAuthorCanEdit: Author-only editing restriction
  • annotationPermissionCallback: Custom annotation permissions

Events​

Version 5 doesn’t support the following events:

  • documentClosed: Document close event
  • textSelected: Text selection event
  • error: Error event
  • busyState: Loading state event

Callbacks​

Version 5 doesn’t support the onCloseFileButtonClicked callback for the close button.

Other options​

Version 5 doesn’t support the shortcuts option for keyboard shortcut configuration.

Next steps​

After completing your migration: