PDF.js Express Plusplay_arrow

Professional PDF.js Viewing & Annotations - Try for free

side menu

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

Compare

play_arrow

Advanced Capabilities

play_arrow

PDF.js Express REST API

play_arrow

Migration Guides

play_arrow

Customize annotation tools

The following features are available in:

check

PDF.js Express Viewer

help_outline

PDF.js Express Viewer is a free viewer with limited capabilities compared to PDF.js Express Plus

check

PDF.js Express Plus

help_outline

PDF.js Express Plus is a commercial PDF SDK for viewing, annotating, signing, form filling and more

Customizing tools is little different from customizing header items. In PDF.js Express Web Viewer UI, they are setup in a special way to be mapped to DocumentViewer's tool modes and grouped into tool group buttons. Thus, PDF.js Express UI provides specific APIs for customizing tools.

Disable/enable tools

By default, PDF.js Express provides shortcuts for most of the tools. If you want users not to use certain tools, you should disable both the DOM element and the shortcut. You can do that with a single API, using one of the following:

And you can check if a tool is disabled using this API:

You can refer to the full list of tool names for the values to pass to these functions.

For example,

WebViewer(...)
  .then(instance => {
    instance.UI.disableTools([ 'AnnotationCreateSticky', 'AnnotationCreateFreeText' ]); // hides DOM element + disables shortcut
    console.log(instance.UI.isToolDisabled('AnnotationCreateSticky'));

    // re-enable every tool when no parameter is passed in
    instance.UI.enableTools();
  });

Update tool property

You can also update tool properties to customize the buttons on the header:

  • buttonImage
  • buttonName
  • buttonGroup
  • tooltip

Change button icon

WebViewer(...)
  .then(instance => {
    instance.UI.updateTool('AnnotationCreateSticky', {
      buttonImage: 'https://www.pdftron.com/favicon-32x32.png'
    });
  });

Change button group

WebViewer(...)
  .then(instance => {
    instance.UI.updateTool('AnnotationCreateRectangle', {
      buttonGroup: 'miscTools'
    });
  });

Event when tool creates an annotation

PDF.js Express provides the annotationAdded event on most annotation tools which is fired when a new annotation is created with that tool.

WebViewer(...)
  .then(instance => {
    const { documentViewer, Annotations } = instance.Core;
    const tool = documentViewer.getTool('AnnotationCreateFreeText');

    // the tool is just a reference to the instance of a tool
    // it could also be something like:
    // const tool = new MyCustomTool(documentViewer);
    tool.addEventListener('annotationAdded', (annotation) => {
      annotation.FillColor = new Annotations.Color(255, 0, 0);
    });
  });

Extend built in tools

PDF.js Express allows you to extend the behavior of tools by overriding certain functions on them. Common functions you might want to override include mouseLeftDown, mouseMove and mouseLeftUp among others.

As an example let's change the highlight tool so that when the user finishes highlighting, the highlight will turn cyan. To override a particular function on a tool we can set its value to a new function.

Note that all of the following code is expected to be run inside a config file.
WebViewer(...)
  .then(instance => {
    const { Tools } = instance.Core;
    // get a copy of the default mouse up function
    const highlightMouseUp = Tools.TextHighlightCreateTool.prototype.mouseLeftUp;
    // set it to our own function
    Tools.TextHighlightCreateTool.prototype.mouseLeftUp = () => {
      // just call the original function for now, passing all the arguments
      highlightMouseUp.apply(this, arguments);
    };
  })

In the example code above we're just calling the original mouse up function that we saved as a variable. Just using that code there should be no visible change in the behavior of the highlight tool.

Let's change the color of the annotation now. All annotation tools have an "annotation" property which is the current annotation being created by the tool. It's created in mouseLeftDown, modified in mouseMove and removed from the tool in mouseLeftUp. This means we need to access it before the original mouseLeftUp function is called.

// in config.js
WebViewer(...)
  .then(instance => {
    const { Tools } = instance.Core;
    const highlightMouseUp = Tools.TextHighlightCreateTool.prototype.mouseLeftUp;
    Tools.TextHighlightCreateTool.prototype.mouseLeftUp = () => {
      if (this.annotation) {
        this.annotation.StrokeColor = new Annotations.Color(0, 255, 255);
      }
      highlightMouseUp.apply(this, arguments);
    };
  })

If you try this code you'll see that it almost works, however you need to click the page again for the annotation to be redrawn in the new color. To fix this we'll need to redraw the annotation inside the tool so that it's updated right away.

// in config.js
WebViewer(...)
  .then(instance => {
    const { Tools, annotationManager } = instance.Core;
    const highlightMouseUp = Tools.TextHighlightCreateTool.prototype.mouseLeftUp;
    Tools.TextHighlightCreateTool.prototype.mouseLeftUp = () => {
      if (this.annotation) {
        this.annotation.StrokeColor = new Annotations.Color(0, 255, 255);
        annotationManager.redrawAnnotation(this.annotation);
      }
      highlightMouseUp.apply(this, arguments);
    };
  })

Now the highlight should change colors right after it's created. As mentioned earlier you can override several different functions on tools and it should work similarly to the example above.