By enabling annotation tools, your end users can annotate the document they are viewing. When they do, the annotations exist only in the viewer, not in the document itself. Unless your application saves these annotations, the user’s annotation work will be lost when they navigate away to a different page.

This guide explains how your application can 1) save the annotations created for a document and 2) show the same document again later with those annotations.

Prerequisites

Saving and loading annotations requires a Professional license. You can evaluate Professional features by setting licenseKey to 'eval' when creating the viewer.

Introduction

Your Application Needs to Keep Track of Which Document Is Annotated

It is important to remember that documents and annotations are separate things in Accusoft PDF Viewer:

• Your application provides the document when it creates the viewer
• Your application can provide annotations to layer on top of the document by calling loadAnnotations after the viewer has been created

While you can load any set of annotations on top of any document, annotations typically only make sense when they are viewed with the document they were created for.

Keeping track of which document a set of annotations were created for is your application’s responsibility. You will need to keep this in mind as you implement a system for saving and loading annotations in your application.

Saving Annotations

To save the annotations which are currently in the viewer, your application needs to:

• Call getAnnotations to get an array of annotation objects from the viewer
• Convert the array to JSON by passing it to JSON.stringify
• Store the JSON somewhere

How you do that last part will depend on your application. Some applications may send the JSON to a REST API responsible for storing it to disk, indicating the document (and perhaps logged in user) the annotations should be associated with. Simple applications might choose to store the JSON in the browser’s local storage.

Here is the beginning of a function you might write to save annotations:

async function saveAnnotations() {
  // Get a copy of the annotation objects from the viewer
  const annotations = await window.myViewer.getAnnotations();

  // Convert the annotation objects to a JSON string
  const annotationsJson = JSON.stringify(annotations);

  // Store the JSON somewhere, associating it with the
  // document being viewed. For example, you might
  // send it to a REST API you own which saves the
  // annotations for a given document id.
}

Knowing When to Save

The viewer has several events that notify you when a user updates an annotation (except in the case of a call to loadAnnotations). You can subscribe to these events and save the updated annotations when appropriate.

window.myViewer.on('annotationsAdded', (addedAnnotations) => {
  // Store the updated annotations' properties somewhere,
  // associating them with the document being viewed.
})

Loading Annotations

To view a document with annotations previously created for it, your application needs to:

• Create a new viewer for the document to be viewed
• Fetch the annotation JSON from wherever you previously stored it
• Convert the JSON back to an array of annotation objects by passing it to JSON.parse
• Call loadAnnotations with the array of annotation objects to put the annotations into the viewer

In code, it will look something like this:

(async () => {
  // Create the viewer
  window.myViewer = await PdfViewerControl.create({
    container: document.getElementById('myContainer'),

    // Use the document that was previously annotated
    sourceDocument: YOUR_SOURCE_DOCUMENT // URL or Uint8Array

    // Use a Professional license key or the value 'eval'
    licenseKey: 'YOUR_LICENSE_KEY',

    // Configure any annotation tools you want in the UI
    allowedControls: {
      ellipseTool: true,
      freehandDrawingTool: true,
      freehandSignatureTool: true,
      lineTool: true,
      rectangleTool: true,
      textHighlightTool: true
    }
  });

  // Fetch the annotation JSON from wherever you stored it
  const annotationsJSON = ...

  // Convert the JSON back to an array of annotation objects
  const annotations = JSON.parse(annotationsJSON);

  // Load the annotations into the viewer
  await window.myViewer.loadAnnotations(annotations);
})();

Related

• How to enable annotation tools