Migrating to PDF.js Express 7.0

PDF.js Express comes with many new features, including a completely redesigned UI!

There are a couple breaking changes and some other changes when migrating from older versions of PDF.js Express.

Breaking changes

New default UI

There is a new default user interface in PDF.js Express 7.0 which has changed the location and structure of some components in the UI. Most APIs will function the same as before.

One of the main changes is to the header toolbars which are split into several groups. You can change the group using setToolbarGroup and you can edit each group using the getHeader function.

WebViewer(...)
  .then(instance => {
    // adds a button to the shapes header
    instance.setHeaderItems(header => {
      const shapesHeader = header.getHeader('toolbarGroup-Shapes');
      shapesHeader.push({
        type: 'actionButton',
        img: '...',
        onClick: () => {
          // perform action
        }
      });
    });
  });

If you want to hide a specific toolbar group, like other DOM elements, they can be hidden by using disableElements.

WebViewer(...)
  .then(instance => {
    // hide the Shapes, Edit and Insert toolbar groups.
    instance.disableElements(['toolbarGroup-Shapes']);
    instance.disableElements(['toolbarGroup-Edit']);
    instance.disableElements(['toolbarGroup-Insert']);
  });

If you are not ready to update to the new UI yet you can still access the previous UI by passing ui: 'legacy' into your WebViewer constructor.

WebViewer({
  ui: 'legacy',
  // other constructor options
}).then(instance => { });

Page numbers instead of page indexes for APIs

Several breaking changes have been made to make sure API signatures are more consistent in PDF.js Express 7.0. We've heard feedback that it can be confusing using some Express APIs because some accept page indexes (starting with zero) and some accept page numbers (starting with one). In 7.0 we've updated all APIs to be page numbers (starting with one) to be consistent.

Generally if you were using APIs on AnnotationManager and DocumentViewer these were already taking in 1-indexed page numbers. If you were using APIs on the Document object, these were taking in 0-indexed page numbers.

The following APIs have been updated to accept page numbers:

• pageComplete
• textSelected
• getSelectedPages
• pageCoordinates
• SearchResult
• pageToWindow
• windowToPage
• getPageTransform
• getPageOffset
• getLinks
• getPageInfo
• getPDFCoordinates
• getTextPosition
• getViewerCoordinates
• loadPageText
• loadThumbnailAsync
• getPageMatrix
• getPageWidth
• getPageHeight
• getPageRotation
• getPageRotations
• setPageRotations
• getPageZoom
• setPageZoom
• getViewportRegionRect
• updateLinks
• stopPageRender
• loadCanvasAsync
• getVisiblePages
• updateView

The following DOM elements have been changed to use page numbers:

• #pageContainer
• #pageWidgetContainer

Deprecations

In PDF.js Express 7.0, we also renamed some constant variables to be more consistent with others. Their previous names are kept for backwards compatibility, though we still encourage you to update them.

• SnapMode
• SearchResults
• SearchMode
• PageRotation