> ## Documentation Index
> Fetch the complete documentation index at: https://webviewer-docs.mupdf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Annotations

## 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:

```javascript theme={null}
{
  "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**

```javascript theme={null}
{
  "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()](/api-reference/annotation#get) method.
Once we have the data we can work with it just as we would with any JSON object.

**Example**

```javascript theme={null}
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()](/api-reference/annotation#add) method.

For example, to write annotations to the document from JSON data stored in local storage we could do the following:

**Example**

```javascript theme={null}
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**

```javascript theme={null}
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()](/api-reference/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**

```javascript theme={null}
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**

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