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
Additionally, PDF JavaScript annotations support interactive objects, such as forms and e-signatures. You can embed rich media annotations, including audio, video, even
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
Your toolkit may also support
Check out our "How to annotate web pages using JavaScript"
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
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
PDF with a cloud polygon annotation
2. Interactive Form and Signature Widgets
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
- Signature
Note: This annotation widget adds e-signatures and fields, which are different from digital signatures. - Push button
An electronic signature annotation added to a PDF
3. Redaction
Use
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.
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
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.
PDF with Approved rubber stamp annotation
6. Rich Media/Multimedia
7. Hyperlink
Adds a
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
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
A custom triangle shape tool created with WebViewer's custom annotations
10. Measurement
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
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
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
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
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
- Automation workflow: Government agencies and financial institutions use automation software to programmaticallystampor 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
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
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
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/webviewerThis 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/publicYou 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
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
Examples
Use the following examples to set annotation permissions, add or edit annotations, or create a drawing annotation. For more information, visit annotation
Set Annotation Permissions
Annotation
- 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
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
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
Related articles
How Can I Tell What’s Inside a PDF? Raster, Vector, Text?
Learn about the content types you find in PDFs and discover tricks & toolsfor figuring out what’s inside your PDF – raster, vector, or text?
PDF Rendering and Viewing: What is the Difference?
In this post, learn about the difference between PDF rendering and PDF viewing, and how the PDFTron PDF SDK unpacks your PDFs for display in a viewer application.
Open Source or Proprietary — What PDF Viewer Engine is Right for My Application?
A comparison of PDF viewer library options and tips on how to decide which PDF rendering and viewing alternative is best for your application. Open source or proprietary?
Related Products
Related Products for Annotations
Related Videos about Annotations
PDFTron SDK
COMPANY