Migrate to WebViewer 12.0

This guide outlines the changes you should review before upgrading from an earlier version to WebViewer 12.0. Use it to identify breaking changes, removed APIs, migration requirements, and any updates needed to ensure a smooth transition.

WebViewer 12.0 modernizes its JavaScript architecture by replacing Webpack with Vite as the build tool and targeting native ES6 (es2022). As part of this transition, several framework-provided base types are now implemented as true ES6 classes, including:

• Annotations.MarkupAnnotation
• Annotations.SelectionModel
• Annotations.ControlHandle
• Tools.GenericAnnotationCreateTool

Custom tools and annotations that extend these types must be updated to use standard ES6 class inheritance patterns.

Legacy ES5 inheritance patterns are no longer supported. For example, constructor calls such as:

1Tools.GenericAnnotationCreateTool.call(this, ...)

Will throw the following error:

1TypeError: Class constructor ... cannot be invoked without 'new'

When migrating custom tools and annotations:

• Use ES6 class syntax.
• Replace Parent.call(this, ...) with super(...).
• Replace Parent.prototype.method.call(this, ...) with super.method(...).

The following example shows how to migrate a custom tool from the legacy ES5 inheritance pattern to standard ES6 class syntax.

1// Old
2const TriangleCreateTool = function (documentViewer) {
3  Tools.GenericAnnotationCreateTool.call(this, documentViewer, TriangleAnnotation);
4};
5
6TriangleCreateTool.prototype = new Tools.GenericAnnotationCreateTool();
7
8TriangleCreateTool.prototype.mouseMove = function (e) {
9  // ...
10};

1// New
2class TriangleCreateTool extends Tools.GenericAnnotationCreateTool {
3  constructor(documentViewer) {
4    super(documentViewer, TriangleAnnotation);
5  }
6
7  mouseMove(e) {
8    super.mouseMove(e);
9    // ...
10  }
11}

We recommend migrating custom tools and annotations to ES6 classes. If build constraints or legacy code requirements prevent this, Reflect.construct can be used as a temporary compatibility bridge in place of .call(this).

1function TriangleCreateTool(documentViewer) {
2  const base = Reflect.construct(
3    Tools.GenericAnnotationCreateTool,
4    [documentViewer, TriangleAnnotation],
5    TriangleCreateTool
6  );
7  Object.assign(this, base);
8}
9
10TriangleCreateTool.prototype = Object.create(Tools.GenericAnnotationCreateTool.prototype);
11TriangleCreateTool.prototype.constructor = TriangleCreateTool;
12
13TriangleCreateTool.prototype.mouseMove = function (e) {
14  Tools.GenericAnnotationCreateTool.prototype.mouseMove.call(this, e);
15  // ...
16};

The Legacy UI is no longer included with WebViewer 12.0. Moving forward, WebViewer uses the Modular UI as the default supported user interface and customization framework. This consolidation provides a single customization path, reduces package size, and simplifies ongoing maintenance and upgrades.

If you're upgrading from WebViewer 11.0 or earlier, review the following migration guidance and update any Legacy UI implementations to their Module UI equivalents. Key changes include:

• The WebViewer constructor no longer supports ui: 'legacy'.
• Legacy UI-specific APIs, including setHeaderItems, have been removed.
• Modular UI is now the only supported UI and remains the default experience.

For more details, see Migrating to V11 Modular UI. For API changes, see WebViewer API changes.

In WebViewer 12.0, event listeners registered with instance.UI.addEventListener() no longer receive a CustomEvent object. Event payloads are now passed directly to the callback as positional arguments.

1// Before
2instance.UI.addEventListener(
3  instance.UI.Events.VISIBILITY_CHANGED,
4  (event) => {
5    const { element, isVisible } = event.detail;
6  }
7);
8

1// After
2instance.UI.addEventListener(
3  instance.UI.Events.VISIBILITY_CHANGED,
4  (element, isVisible) => {
5    // ...
6  }
7);

If your event handlers access values using event.detail, update them to accept the event payload directly as callback arguments.

Argument patterns by event

The following events provide multiple positional arguments:

1visibilityChanged(element, isVisible)
2annotationFilterChanged(types, authors, colors, statuses, checkRepliesForAuthorFilter)
3panelResized(element, width)
4thumbnailDropped(before, after, count)
5activeDocumentViewerChanged(active, previous)
6languageChanged(previous, next)

The following events provide a single object or array argument:

1themeChanged(theme)
2modularUIImported(components)
3outlineBookmarksChanged(data)
4userBookmarksChanged(bookmarks)

The following events don't provide a payload:

1viewerLoaded()
2fileDownloaded()
3multiViewerReady()

Refer to UI.Events for the complete payload definition for each event.

UI events dispatched on window continue to use CustomEvent for backward compatibility. However, the structure of event.detail has changed to match the new event listener payload format.

1// Before
2window.addEventListener('tabDeleted', (event) => {
3  const { src, options, id } = event.detail;
4});
5

1// After
2window.addEventListener('tabDeleted', (event) => {
3  const [src, options, id] = event.detail;
4});
5

Review any code that reads values from event.detail and update it to use the new payload structure for affected events.

Updated event.detail formats

The following events now expose payload values as arrays instead of objects:

1visibilityChanged
2panelResized
3thumbnailDropped
4annotationFilterChanged
5activeDocumentViewerChanged
6languageChanged
7compareAnnotationsLoaded
8documentMerged
9tabAdded
10tabMoved
11beforeTabChanged
12afterTabChanged
13beforeTabDeleted
14tabDeleted

The following events now return a single value instead of an object:

1fullscreenModeToggled
2  { isInFullscreen } → boolean
3
4modularUIImported
5  { importedComponents } → component value

The following events now return a single-element array:

1userBookmarksChanged
2selectedThumbnailChanged

The payload format for the following events has not changed:

1themeChanged
2outlineBookmarksChanged
3viewerLoaded
4fileDownloaded
5multiViewerReady

WebViewer has strengthened the security boundaries of the embedded JavaScript runtime for PDF documents. Embedded JavaScript is no longer executed through eval and now runs in a more restricted execution environment.

Embedded JavaScript that relies on any of the following may no longer work as expected:

• Dynamic code execution.
• Direct access to runtime or browser environment objects.
• Unsupported JavaScript language features.

Review and test any embedded JavaScript used in your PDF documents to ensure compatibility with the updated runtime.

Replacement APIs may be located in a different namespace or class than the removed API. Review the replacement column carefully when updating your implementation.

The following WebViewer APIs were deprecated in previous releases and have been removed in v12.0.

Core.AccessibleReadingOrderManager

Core.Annotations

Core.DocumentViewer

Core.Tools

UI

The following DOCX Editor APIs were deprecated in previous versions and have been removed in v12.0.

Core.Document

Core.Document.OfficeEditor

Undocumented Office Editor APIs also removed in v12.0:

• Core.Document.OfficeEditor.toggleMainCursorStyle()
• Core.Document.OfficeEditor.freezeMainCursor()
• Core.Document.OfficeEditor.showMainCursor()
• Core.Document.OfficeEditor.getContentListType()

The following Spreadsheet Editor APIs have changed in v12.0. The SpreadsheetEditorManager.setEditMode() method is no longer asynchronous.

Core.SpreadsheetEditorDocument