Free trial

Pick a framework to get started

close

Get Started

play_arrow

Learn more

play_arrow

Common use cases

play_arrow

Open a document

play_arrow

Save a document

play_arrow

Viewer

play_arrow

UI Customization

play_arrow

Annotations

play_arrow

Collaboration

play_arrow

Forms

play_arrow

Signature

play_arrow

Searching

play_arrow

Measurement

play_arrow

PDF.js Express REST API

play_arrow

Migration Guides

play_arrow

Config files

PDF.js Express Web Viewer creates the UI app inside an iframe so that Core namespaces and classes are encapsulated. The iframe window and document object are still accessible through contentWindow and contentDocument, but it can still be tricky to run scripts or listen to events happening inside the iframe.

PDF.js Express Web Viewer provides an option referred to as a "config file". It's just an ordinary JavaScript file, but it will be executed in the context of the iframe. This gives you easy access to the Document, DocumentViewer and AnnotationManager objects (among others) which can allow you to make more complicated customizations.

To instantiate PDF.js Express Web Viewer with a config file you just need to set the config option in the WebViewer constructor. For example:

WebViewer({
  initialDoc: "mydoc.pdf",
  config: "path/to/my/config/file.js" // relative to your HTML file
}, viewerElement);

Useful events

The config file is executed even before the core objects are instantiated, so you won't be able to call core functions immediately. You can listen for events on the HTML document object that will notify you at key points.

The first important one is the viewerLoaded event. viewerLoaded will be fired after app has been rendered, and at this point you'll be able to access the docViewer variable before the document has loaded. For example:

window.addEventListener('viewerLoaded', () => {
  docViewer.setMargin(20);
  docViewer.on('fitModeUpdated', fitMode => {
    console.log('fit mode changed');
  });
});

Another important event is documentLoaded. Once documentLoaded has fired you can access Document as well as functions related to the page number on ReaderControl, DocumentViewer and AnnotationManager. For example:

window.addEventListener('documentLoaded', () => {
  const doc = docViewer.getDocument();
  doc.loadThumbnailAsync(0, thumb => {
    const myThumbnailDiv = document.getElementById('myThumbnailDiv');
    myThumbnailDiv.appendChild(thumb)
  });

  const annotManager = docViewer.getAnnotationManager();
  const rectangle = new Annotations.RectangleAnnotation();
  rectangle.PageNumber = 2;
  rectangle.X = 100;
  rectangle.Y = 100;
  rectangle.Width = 250;
  rectangle.Height = 250;
  rectangle.Author = annotManager.getCurrentUser();
  annotManager.addAnnotation(rectangle);

  docViewer.displayLastPage();
});

Passing custom data

Sometimes you might want to send custom data from the "outer" page (with the WebViewer constructor) to the "inner" page (your config file). To do this you can use the custom option in the WebViewer constructor. The property expects a string value. So for example to pass an object:

const myObj = {
  startPage: 10
};

WebViewer({
  custom: JSON.stringify(myObj)
}, viewerElement);

Then inside the config file you access this data as follows:

let custom;

window.addEventListener('viewerLoaded', () => {
  custom = JSON.parse(readerControl.getCustomData());
  console.log(custom.startPage); // outputs 10
});

window.addEventListener('documentLoaded', () => {
  const docViewer = readerControl.docViewer;
  docViewer.setCurrentPage(custom.startPage);
});

Accessing outer page inside the iframe

If you want to access the outer page from inside the iframe, for example from code in your config file, you can access the parent window using window.parent. So if you defined an API that's loaded on your HTML page, you could access it from inside the iframe like window.parent.myApi.myFunction().

Accessing WebViewer instance from the config file

If you want to access the WebViewer instance from the config file, you can use readerControl in place of the instance argument normally returned when instantiating WebViewer.

Here is an example of the Viewing sample converted to a config file:

window.addEventListener('viewerLoaded', () => {
  window.parent.document.getElementById('select').onchange = (e) => {
    readerControl.loadDocument(e.target.value);
  };

  window.parent.document.getElementById('file-picker').onchange = (e) => {
    const file = e.target.files[0];
    if (file) {
      readerControl.loadDocument(file);
    }
  };

  window.parent.document.getElementById('url-form').onsubmit = (e) => {
    e.preventDefault();
    readerControl.loadDocument(window.parent.document.getElementById('url').value);
  };
});