Some test text!

Jun 29 2022

A Comprehensive Guide to PDF Annotations with JavaScript

by Heather Dinsdale

This guide discusses PDF annotations with JavaScript, and how to add them to your project.

And since PDFTron has much expertise in this field, we’ll also touch on the annotation capabilities in the PDFTron and WebViewer SDK.

What are PDF Annotations?

Let’s start at the beginning – what is a PDF annotation? It is an object such as text, graphics, highlights, text boxes, or redaction marks that users add to a document. You can incorporate an SDK or library into your solution, which allows users to add annotations to documents. 

Annotations are added to an existing document, without changing the underlying PDF content. You can add comments or drawings to the PDF for review and collaboration, or even

the annotations separately into a database for more fine-grained
control
when storing the annotations and applying version control.

Additionally, PDF JavaScript annotations support interactive objects, such as forms and e-signatures. You can embed rich media annotations, including audio, video, even

into a PDF file, or add hyperlinks, watermarks, and a lot more.

A popular way to annotate documents is using a web app. You can annotate PDF documents in your project using JavaScript, in addition to annotations via native languages using the PDFTron SDK.

Why Add PDF Annotations?

So why embed PDF annotation features into your solution? The answer is easy: because PDF annotations are versatile. (PDFTron supports 35+ types.) The PDF format has annotation types to support many use cases and workflows. 

And, as a developer, you can customize documents with annotations programmatically – placing watermarks, hyperlinks, images and other annotations via code.

Annotating Images or Office Files

This article focuses on PDFs, but annotations aren’t limited to just PDFs. You can also add notations or discussion threads to Word documents, contracts or reports, or complex designs and construction drawings.

With the right toolkit, annotations are virtually file-format agnostic. Add them to images, Office files, even videos. For example, dynamic client-side

supports annotation on top of your Office files in a web app without pre-processing them.

Your toolkit may also support

and
web site
annotations. Each format uses the same WebViewer component and rich array of PDF annotation to simplify integration, support, maintenance, and extension.

Check out our "How to annotate web pages using JavaScript"

for more information.

Client-Side JS Conversion and Annotation

There are numerous reasons for adding JavaScript annotations in a client-side app.

  • They work well when privacy is important. You can minimize transfers across a network or to/from servers when you have sensitive data.
  • They provide cost-effective feature scalability, since client-side reduces server and network resource usage.
  • User experience is consistent and reliable, because viewing and annotation are not impacted by network latency or servers under heavy load.

Markup vs. Annotation

There are two different ways to use an annotation in a PDF.

  • Markup annotations: Used to mark up content in a PDF file or other documents. Markup annotations are common in document reviews, when multiple people collaborate, create text comments, or add notes.
  • Non-markup annotations: These are used to add interactive widget objects like a signature or fillable form fields to an existing PDF.

PDF Annotations Types

The PDF specification supports

annotations, and the PDFTron JavaScript annotation library adds nine more types. You can even create
custom
annotations, changing the appearance and behavior.

Let’s look at some of the different PDF annotation types, and where they fit into applications.

1. Drawing and Shape

Add these annotation types to quickly draw attention to suggestions or edits, over images or blocks of text, or to highlight information in the document. The shapes and drawings provide a very visible way to see reviewers' suggestions.

  • Freehand/Ink
  • Rectangle
  • Ellipse
  • Polygon
  • Cloud polygon 
  • Polyline 
  • Line 
  • Arrow 
  • Free Text
  • Callout
Drawing and shape annotation example screen

PDF with a cloud polygon annotation

2. Interactive Form and Signature Widgets

enable interactivity within a PDF document. Add them along with signature widgets to sign, form fill, and capture filled-in information.

The form fields are a collection of interactive elements. These include text boxes, checkboxes, radio buttons, drop-down lists, or push buttons, which gather user information interactively.

Form fields exist as widget annotations and display independently of the field itself. For example, on a loan document, you can add a signature widget that appears on every page for the primary applicant’s signature. Other pages may require multiple signatures for both the applicant and any co-signers. 

Check out our online form builder

.

Interactive form and signature widgets example screen

An electronic signature annotation added to a PDF

3. Redaction

Use

annotations to remove sensitive data within your PDFs. PDFTron’s JS redaction does not just obscure or mask sensitive data with a dark highlight or image like many browser-based tools. It actually modifies the underlying PDF file to prevent malicious retrieval of any redacted information, including text, images, parts of images, and certain metadata in a client-side application.

There are two stages of a redaction annotation:

  • Draft redaction marks/highlights that allow other users to verify content for redaction.
  • Redaction labels placed on top of content after it’s redacted. Labels can be simple basic black rectangles. With the PDFTron SDK, you can customize how redaction labels look and provide general context as to what was redacted.
Redaction annotation example screen

Use redaction annotation on photos and fields, and add text labels

4. Text
Text annotations add text comments, but text markup annotates the actual text instead,. This is done by highlighting and underlining the text, or adding squiggly lines or text strikeouts to note text to remove or change. 

  • Text: Text comment boxes and sticky notes
  • Text markup annotations: Highlight, underline, strikeout, squiggly, and caret
Text annotation example screen

PDF using text annotations like highlighting, underlining, and text comment

5. Rubber Stamp

Use these annotations to add a stamp to your PDF the same as you might stamp a hardcopy document. This conveys a message quickly to the reader, that maybe the PDF is private, confidential, copyrighted, or a draft version. It can also convey the document status during a review, if it’s stamped as Approved, Rejected, etc.

Rubber stamp annotation example screen

PDF with Approved rubber stamp annotation

6. Rich Media/Multimedia

annotations can be used to embed videos and sound files in PDF documents. When a document is opened in a compliant reader, users can then play them back directly as part of the page content, usually by just clicking on the video.

7. Hyperlink

Adds a

or intra-document link annotation to a PDF file page.

8. Images and File Attachments

Adds images or file attachment annotations to your PDF.

9. Custom annotations

Depending on your toolkit, you can create your own annotations and

them.

For example, change the appearance or behavior of annotations, selection boxes, and control handles. You can also build customized annotations to appear in other PDF viewers.

Check out our custom annotations

for basic examples.

Custom annotation example screen

A custom triangle shape tool created with WebViewer's custom annotations

10. Measurement

the area, distance and perimeter in PDFs using JavaScript. The PDFTron SDK tools add annotations and provide a UI to modify common properties. There is also an API for fine-grained control.

Measurement annotations are common in the construction industry, where they are used to dimension rooms or spaces in drawings, and estimate the necessary materials and labor. Check out our measurement tool

.

  • Distance measurement
  • Arc measurement
  • Perimeter measurement
  • Area measurement
  • Ellipse area measurement
  • Rectangular area measurement
  • Cloud rectangular area measurement
  • Count measurement

Measurement annotation example screen

Measure a room's diameter with the measurement tool annotation

Use Cases 

So now you know what annotations are, how do you implement them? There are various methods, but only some offer all 26 standard types. The PDFTron SDK supports all standard annotations, plus nine additional types, and custom annotations. 

With WebViewer, your users can add annotations directly in the UI, using the annotations toolbar. You can also add annotations to PDFs programmatically, using code to add watermarks directly in the client application.

There are other use cases as well, such as: 

Threaded conversations
Annotations can provide

and discussion on top of content. In WebViewer, you can attach threaded conversations via comments, or reply to comments on any annotation.

Many PDF viewers add single notes or comments, which is a messy format for reviews and conversations. For example, if a copy editor leaves a comment on a particular paragraph, there’s no easy way for the author to quickly see or respond to it in place. With multiple comments scattered across the page, it becomes nearly impossible to piece together the conversation flow—which is not conducive to discussion or quality output.

Instead, with threaded conversations, the editor can add a comment, and other people can reply directly to it, creating a chain discussion. It keeps the comments and replies tidy, visible, and easy to find and respond to.

For more information about document reviews and sample code:

Measurement
Measurements are commonly used in construction and engineering workflows on PDF drawings exported from CAD and BIM programs. Use annotations with measurement tools to calculate area dimensions, measure between lines, or trace perimeters in engineering drawings in a browser or app with JavaScript. You can also add measurement tools to your application and measure the area, distance, or perimeter for construction plans.

For more information and sample code:

Adding stamps
Much like rubber stamping a real-world document, PDF

annotations denote a document's status (i.e., Approved, Rejected, Voided, etc.). With WebViewer, dynamically create stamps with custom text, like who created the stamp, or the date and time it was created.

Electronic signatures
You can also approve documents you’ve reviewed using an electronic signature annotation. This adds a simple visual signature to your document. It is a visually identifiable autograph, and can be

in a database.

For more information about e-signatures:

Note: Electronic signatures are created as images, hand drawn, photographs, or typed text. They are not digital signatures, which are more complex, and require a digital ID or certificate from a certification authority (self-signed or a third party).

For more information about digital signatures:

Adding Annotations: UI vs. Programmatically

After implementing them, you can add PDF JavaScript annotations in two ways: from the UI, or programmatically.

1. UI-based: For this approach, users access annotations with tools in the viewer interface.

PDFTron adds all annotations, including redactions and watermarks, in the browser client, so no data is sent out to third-party servers, and the information never leaves the browser environment. Since you're relying less on server and network resources, the solution is more reliable and scalable for your users.

2. Programmatically: You can also apply annotations automatically, via code. This includes adding watermarks to sensitive documents.

  • Custom annotations: Some PDF programs apply personal logos and convert text into clickable links.

PDFTron’s WebViewer provides many APIs to interact with and customize annotations programmatically. For more information, see

for your viewer.

  • Automation workflow: Government agencies and financial institutions use automation software to programmatically
    stamp
    or insert timestamps on digital documents.  

Adding Annotations via JavaScript

There are two ways to incorporate PDF annotations with JavaScript – build your own solution, or use an existing library.

1. Create a JavaScript Solution
Creating your own solution gives you more control. However, it requires much work, and understanding minute details. You must carefully conform to the PDF specification, handle edge cases, ensure your annotations work with other widely-used PDF readers, and interoperate with the PDF specification standard XFDF format to store annotations. 

2. Use an Existing Solution

Building support for custom annotations, form filling, or signature features requires understanding the entire process -- which is handled automatically within a commercial SDK UI.

For example, the PDFTron SDK supports annotations, even in its trial version, so users can process annotations directly in WebViewer.

WebViewer exposes several APIs to easily add annotations with a professional PDF and Office viewer component. You can then

your preferred annotations and tool groupings in the toolbar ribbon, or add your own annotations programmatically and headlessly within your existing experience and UI. WebViewer also works with all major JS frameworks so it fits easily into your project. Visit our
download center
to try it with your preference.

WebViewer also adds support beyond what’s provided in the PDF specification, including support for custom annotation types.

Install WebViewer for Annotations

There are different ways to install WebViewer, but we’ll use NPM for this example.

To use WebViewer for annotations, download and install versions 8.0+ via

. (The following examples are all for version 8.0+.)

Since WebViewer requires static resources to be served (which cannot be bundled), an extra step involves manually copying static files into your dist directory.

Prerequisites

First, install

and
NPM
.

WebViewer does not require Node, NPM, or node_modules. It is only recommended to run the samples.

1. Install via NPM

Run the following command in your project:

npm i @pdftron/webviewer

This installs the main JS entrypoint, and downloads static assets required for WebViewer to run.

2. Copy static assets

Next, copy the static assets required for WebViewer to run into a public location that is served via HTTP/HTTPS (usually a dist or build folder). The static files are located in

node_modules/@pdftron/webviewer/public

You can add a script to your package.json that moves the static files for you after your build completes.

This copies all required files into the dist/public folder after your build is complete.

{
  "scripts": {
    "move-static": "cp -a ./node_modules/@pdftron/webviewer/public/. ./dist/public/webviewer",
    "build": "mybuildscript && npm run move-static"
  }
}

3. Usage

When using WebViewer in your code, you must tell it where you copied these static files using the path parameter.

For example, if you copied the static files into dist/public/webviewer, your code would look something like this:

import WebViewer from '@pdftron/webviewer'
 
WebViewer({
  path: '/public/webviewer',
}, document.getElementById('viewer'))
  .then(instance => {
    const { UI, Core } = instance;
    const { documentViewer, annotationManager, Tools, Annotations } = Core;
    // call methods from UI, Core, documentViewer and annotationManager as needed
 
    documentViewer.addEventListener('documentLoaded', () => {
      // call methods relating to the loaded document
    });
 
    instance.UI.loadDocument('http://fileserver/documents/test.pdf');
  })

For information on the next steps, visit

.

Integrate PDFTron Annotations

The PDFTron SDK provides annotations right out of the box, using a toolbar in the UI or programmatically by writing code for the annotation types.

When writing code, add the annotation after the document loads. For example, to add it immediately after the document loads, use the

event:

 

WebViewer(...)
  .then(instance => {
    const { documentViewer, annotationManager, Annotations } = instance.Core;

    documentViewer.addEventListener('documentLoaded', () => {
      // create annotation here
    });
  });

Annotation type properties and functions are available in the annotation API

.

For more information and links to samples, visit the

page. 

Examples

Use the following examples to set annotation permissions, add or edit annotations, or create a drawing annotation. For more information, visit annotation

in JavaScript.

Set Annotation Permissions

Annotation

are flexible and customizable. WebViewer supports client-side user permissions to control who modifies which annotations. By default, users can only modify annotations they create, but you can customize this. The permissions include:

  • Admin: Fully allowed to create/reply to/edit/delete any annotations
  • User: Allowed to create/reply to any annotations, but only allowed to edit/delete their own annotations
  • Read only: Not allowed to create/reply to/edit/delete any annotations

Define your own logic by using the

function on AnnotationManager.

This function takes a callback function you defined and returns it true if you give the current user permission to modify the annotation, or returns false otherwise.

WebViewer(...)
  .then(instance => {
    const { annotationManager } = instance.Core;
 
    annotationManager.setPermissionCheckCallback((author, annotation) => {
      // the default permission check that is used
      // you can combine this with your own custom checks
      const defaultPermission = annotation.Author === annotationManager.getCurrentUser();
      // any annotation with 50% opacity will also be editable regardless of the author
      const customPermission = annotation.Opacity === 0.5;
 
      return defaultPermission || customPermission;
    });
  });

Add or Edit PDF Annotations

The following sample code adds or edits annotations using the PDFTron SDK JavaScript PDF annotation library. The sample annotation types include: hyperlink, intra-document link, stamp, rubber stamp, file attachment, sound, text, free-text, line, circle, square, polygon, polyline, highlight, squiggly, caret, and ink. 

Learn more about our

and
PDF Annotation Library
.

Create a Drawing Annotation

Use this example to create a rectangle JavaScript PDF annotation. Creating other types of annotations is similar.

WebViewer(...)
  .then(instance => {
    const { Annotations, annotationManager, documentViewer } = instance.Core;
 
    documentViewer.addEventListener('documentLoaded', () => {
      const rectangleAnnot = new Annotations.RectangleAnnotation();
      rectangleAnnot.PageNumber = 1;
      // values are in page coordinates with (0, 0) in the top left
      rectangleAnnot.X = 100;
      rectangleAnnot.Y = 150;
      rectangleAnnot.Width = 200;
      rectangleAnnot.Height = 50;
      rectangleAnnot.Author = annotationManager.getCurrentUser();
 
      annotationManager.addAnnotation(rectangleAnnot);
      // need to draw the annotation otherwise it won't show up until the page is refreshed
      annotationManager.redrawAnnotation(rectangleAnnot);
    })
  })

Import/Export Annotations

One option is to use XFDF files to save and load annotations. You can use AJAX requests to save and load the XFDF string from the server, and set up the server to write and read XFDF files.

WebViewer(...)
  .then(instance => {
    const { documentViewer, annotationManager } = instance.Core;
 
    documentViewer.setDocumentXFDFRetriever(async () => {
      // load the annotation data
      const response = await fetch('path/to/annotation/server');
      const xfdfString = await response.text();
 
      //  <xfdf>
      //     <annots>
      //       <text subject="Comment" page="0" color="#FFE6A2" ... />
      //     </annots>
      //  </xfdf>
      return xfdfString;
    });
 
    // later save the annotation data
    // widgets and links will remain in the document without changing so it isn't necessary to export them
    annotationManager.exportAnnotations({ links: false, widgets: false }).then(xfdfString => {
      fetch('path/to/annotation/server', {
        method: 'POST',
        body: xfdfString // written into an XFDF file in server
      });
      // Full samples are available at the end of this section.
    })
  })

For more information, see

.

Related Resources

Learn more about PDF annotations from the following resources:

Conclusion

In this article, we described what PDF annotations are and the rich functionality they bring to projects with the right annotation library. We also covered:

  • Potential use cases for annotations in an application
  • How to annotate a PDF in JavaScript using PDFTron's annotations, which require minimal code to get up and running
  • Examples of creating and adding annotations 

To learn more about PDFTron's customizable annotations, visit our

or download a
free trial
of the PDFTron SDK. Our product specialists and the engineers who built the product are delighted to answer any questions, so don't hesitate to
drop us a line
.

Related articles

thumbnail

How to View DOCX in an Angular Web App

We explain how to open DOCX in an Angular viewer and so much more with PDFTron WebViewer.

thumbnail

How to Open DOCX in a Vue Web App

Open DOCX files in a Vue web app and more with PDFTron WebViewer.

thumbnail

A Comprehensive Guide to PDF Annotations with JavaScript

This article discusses what PDF annotations with JavaScript are, and how to add them to your solution.

HEATHER DINSDALE

Marketing Content Writer

Content/technical writer, editor, Parrot Head.

Related Products

Share this post

Upcoming Webinar: SDK Features Preview and Live Run-Through | July 14, 2022 at 11 am PT

PDFTron SDK

The Platform

NEW

© 2022 PDFTron Systems Inc. All rights reserved.

Privacy

Terms of Use