Annotations - MuPDF WebViewer

Working with Annotations

Annotations can be read from, and written to, a MuPDF document instance. In this way a developer is able to separately store annotations and programmatically manage them.

Annotation data format

Annotations are read and written to the MuPDF WebViewer in a JSON format, referenced as Annotation[] the format is as follows:

{
  "annotations": [
    {
      "oid": 0,
      "type": webViewer.refs.annotation.tool.TYPE_NAME,
      "pageIndex": 0,
      ...
    },
    ...
  ]
}

The data within each object is dependent on the annotation type, for example a highlight annotation might be as follows: Example

{
  "annotations": [
    {
      "oid": 30,
      "type": webViewer.refs.annotation.tool.HIGHLIGHT,
      "pageIndex": 0,
      "name": "81ba5e29-1930-4453-b594-f5771cf83a57",
      "rect": {
        "top": 10,
        "bottom": 40,
        "left": 10,
        "right": 40
      },
      "opacity": 1,
      "rotation": 0,
      "createdAt": "D:20250710153823+01'00'",
      "modifiedAt": "D:20250710153823+01'00'",
      "author": "Jane Doe",
      "canBePrinted": true,
      "locked": false,
      "rects": [
        {
          "top": 10,
          "bottom": 40,
          "left": 10,
          "right": 40
        }
      ],
      "fillColor": "#ffd100"
    }
  ]
}

Reading annotation data

To read annotation data from a document we use the annotation.get() method. Once we have the data we can work with it just as we would with any JSON object. Example

async function saveAnnotationsLocally() {
  const annotations = await webViewer.annotation.get();
  let annotsJSON = JSON.stringify(annotations);

  // for example store the data in local storage
  localStorage.setItem('pdfAnnotations', annotsJSON);
  webViewer.toast.show({
    type: 'success',
    content: 'Annotations saved locally'
  });
}

Writing annotation data

To write annotation data to a document we use the annotation.add() method. For example, to write annotations to the document from JSON data stored in local storage we could do the following: Example

const savedAnnotations = JSON.parse(localStorage.getItem('pdfAnnotations') ?? '{ "annotations": [] }');
if (savedAnnotations?.annotations.length > 0) {
  await webViewer.annotation.add(savedAnnotations);
  webViewer.toast.show({
    type: 'notification',
    content: 'Annotations loaded',
  });
}

Or to add a note annotation to a document we might do: Example

const annotations = [ {
  type: webViewer.refs.annotation.tool.HIGHLIGHT,
  pageIndex: 0,
  rects: [{
    top: 10,
    bottom: 40,
    left: 10,
    right: 40,
  }],
  fillColor: '#ffd100',
} ];

await webViewer.annotation.add({ annotations });
webViewer.toast.show({
    type: 'notification',
    content: 'Annotations added'
});

Removing annotation data

Annotations can be removed from a document by using the annotation.remove() method. To remove an annotation, provide either its oid (unique across the document) or its name and pageIndex (since name is only unique within a page). Example

webViewer.annotation.remove({ annotations: [ { name: "squiggle_1", pageIndex: 0 } ] }); // remove by name
webViewer.annotation.remove({ annotations: [ { oid: 30 } ] }); // remove by oid

Setting the Annotation Author

When creating annotations in MuPDF WebViewer you can predefine the author of the annotation by listening to the ANNOTATION_CREATE event and then setting the annotation metadata for the author name. Example

webViewer.addEventListener(webViewer.refs.event.type.ANNOTATION_CREATE, event => {
    event.data.annotation.author = 'Jane Doe';
    webViewer.annotation.set({
        annotations: [
            event.data.annotation,
        ],
    });
});

​Working with Annotations

​Annotation data format

​Reading annotation data

​Writing annotation data

​Removing annotation data

​Setting the Annotation Author