Supporting Link Annotations in PDFs Using JavaScript

PSPDFKit for Web supports common types of link annotations, including page, web, and email links. Tapping on such a link will automatically invoke the saved action (see PDF actions), as well as the correct event, such as changing the page or opening a URL.

By default, PSPDFKit will parse annotations, including links, from a document.

Link annotations are always read-only for the user; the position and action can be changed programmatically using the regular annotations API or via the UI.

For more information on links, please refer to the API documentation.

Adding Link Annotations to PDFs

Add a clickable link to an area in one of the following ways:

• Programmatically

• Using the built-in user interface (UI)

Adding Link Annotations Programmatically

To add a link annotation programmatically, follow the steps below.

1. Create an action property that will be executed when clicking a link:

const action = new PSPDFKit.Actions.GoToAction({ pageIndex: 10 });

2. Add the action as part of the link annotation:

// Create a link annotation on the first page.
const annotation = new PSPDFKit.Annotations.LinkAnnotation({
  pageIndex: 0,
  boundingBox: new PSPDFKit.Geometry.Rect({
    left: 10,
    top: 20,
    width: 30,
    height: 40
  }),
  action: action
});

Editing Link Annotations Programmatically

To edit a link annotation programmatically, use the update method:

// Create a new `URIAction`.
const newAction = new URIAction({
  uri: "pspdfkit://example.com"
});

// Update the link annotation with the newly created action.
const editedAnnotation = annotation.set("action", newAction);

Adding Link Annotations Using the Built-In UI

To add a link annotation using the built-in UI, follow the steps below.

1. Tap the link annotation icon in the contextual menu.

2. Drag the annotation to its place on the page.

3. Choose between linking to a page in the current document or linking to a website.

Editing Link Annotations Using the Built-In UI

To edit a link annotation using the built-in UI, long-press the link annotation and then click Edit.

Customizing Link Behavior

It’s possible to execute custom application code and even prevent the default click behavior for links by registering an event handler for the annotations.onPress event on the PSPDFKit instance:

PSPDFKit.load(...).then(instance => {
  instance.addEventListener("annotations.press", event => {
    if (event.annotation instanceof PSPDFKit.Annotations.LinkAnnotation) {
      event.preventDefault();
      console.log(event);
    }
  });
});

PSPDFKit.load(...).then(function (instance) {
  instance.addEventListener("annotations.press", function (event) {
    if (event.annotation instanceof PSPDFKit.Annotations.LinkAnnotation) {
      event.preventDefault();
      console.log(event);
    }
  });
});

Read more about the AnnotationsPressEvent.

Autodetecting Links

PSPDFKit can optionally analyze the page contents and automatically add links to URLs. This is slightly expensive since text needs to be parsed and analyzed, but it’s done in a background process, so in most cases, it’s not noticeably slower. This feature is turned off by default.

You can use Configuration#enableAutomaticLinkExtraction to enable autodetection in Standalone mode, or use the AUTOMATIC_LINK_EXTRACTION environment variable to enable it in Server-Backed mode.