Skip to main content

​
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 mupdfwv.Annotation[] the format is as follows: 
{
    "annotations": [
        {
            "oid": 0,
            "type": "",
            "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": "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 mupdf.annotation.get();
    let annotsJSON = JSON.stringify(annotations)

    // for example store the data in local storage
    localStorage.setItem('pdfAnnotations', annotsJSON);
    mupdf.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 mupdf.annotation.add(savedAnnotations);
    mupdf.toast.show({
        type: 'notification',
        content: 'Annotations loaded'
    });
}
Or to add a note annotation to a document we might do: Example 
let json = `
{
    "annotations": [
        {
            "oid":0,
            "type": "TEXT_POPUP",
            "pageIndex": 0,
            "name": "9b2",
            "rect": {
                "top": 10,
                "bottom": 40,
                "left": 10,
                "right": 40
            },
            "opacity": 1,
            "rotation": 0,
            "createdAt": "D:20250617223659+01'00'",
            "modifiedAt": "D:20250617223704+01'00'",
            "author": "Jane Doe",
            "canBePrinted": true,
            "locked": false,
            "contents": "Hi there!",
            "fillColor": "#ff00ff",
            "position": {
                "x": 100,
                "y": 100
            },
            "popupNote": {
                "rect": {
                    "top": 10,
                    "bottom": 40,
                    "left": 10,
                    "right": 40
                }
            }
        }
    ]
}  
`
const annotData = JSON.parse(json);

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

​
Removing annotation data

Annotations can be removed from a document by using the annotation.remove() method. All that is required is to send through the name or oid identifier along with the pageIndex for the annotation you want to remove. Example 
mupdf.annotation.remove({annotations:[{name:"squiggle_1", pageIndex:0]); // remove by name
mupdf.annotation.remove({annotations:[{oid:30, pageIndex:1]); // 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 
mupdf.addEventListener(mupdf.refs.event.type.ANNOTATION_CREATE, event => {
    event.data.annotation.author = 'Jane Doe';
    mupdf.annotation.set({
        annotations: [
            event.data.annotation,
        ],
    });
});
⌘I