Subscribe or Unsubscribe to API Events

PSPDFKit for Web comes with an API to subscribe and unsubscribe to framework-level events that are dispatched every time actions occur. This API is available on every Instance and consists of two methods:

• Instance#addEventListener

• Instance#removeEventListener

A comprehensive list of and detailed documentation for every event is available in the addEventListener docs.

Once PSPDFKit for Web is initialized, registering an event listener is straightforward:

function listener(createdAnnotations) {
  console.log(createdAnnotations);
}

instance.addEventListener("annotations.create", listener);

It is important to define the listener function separately so that it can be used later on to remove the event listener:

instance.removeEventListener("annotations.create", listener);

Please note that adding an unknown event will raise a PSPDFKit.Error:

try {
  instance.addEventListener("doesnotexist", () => {});
} catch (error) {
  error instanceof PSPDFKit.Error; // => true
}

Listener Arguments

With the exception of exact single-value arguments like numbers and strings, PSPDFKit for Web invokes event listeners with immutable data structures. When this occurs, you can use the toJS method to convert them to plain JavaScript objects:

function listener(createdAnnotations) {
  console.log(createdAnnotations.toJS()); // => Array of annotation objects
}

instance.addEventListener("annotations.create", listener);

Here’s an example of native JavaScript argument types:

function listener(zoom) {
  console.log(zoom); // => 1.5 for example
}

instance.addEventListener("viewState.zoom.change", listener);

Registering Events on the Internal Viewer document and window

PSPDFKit for Web is rendered inside of an iframe, and because of this, we expose its document and window objects on each instance as contentDocument and contentWindow.

By using a reference to these objects, it is possible to register regular DOM events on elements inside of the viewer frame:

instance.contentDocument.addEventListener("mouseup", handleMouseUp);

As a general rule, we advise against registering events on the objects, since this might easily interfere with internal application logic. When possible, please use PSPDFKit for Web events.

Event Examples and Documentation

All of the available events are documented, with examples, on the documentation page for PSPDFKit.Instance. Please don’t hesitate to contact us if specific use cases are not covered in the API docs.