Annotations

Annotations are the markup objects users add to a PDF — highlights, shapes, free text, stamps, signatures, redactions, and more. This guide covers the UI-side annotation features and the import/export APIs.

Annotation rendering, data model, and PDF-space coordinate handling live in the closed-source Core engine (packages/core/src/annotation/). The UI layer (documented here) drives the engine through the core bridge and mirrors annotation state in the document Pinia store.

Annotation types

Category	Types
Text markup	Highlight, Underline, Strikeout, Squiggly
Shapes	Rectangle (square), Circle, Line, Arrow, Polyline, Polygon, Cloudy, Arc, Curve
Free text	Freetext, Callout
Drawing	Ink
Stamps & images	Stamp, Image
Links	Link
Forms	Textfield, Checkbox, Radiobutton, Listbox, Combobox, Pushbutton, Signature (see Forms)
Security	Redaction, Remove (see content editor / security)

Type aliases

Some types share engine implementation:

• circle without measure → square
• ink with measure → curve
• ink with arc points → arc

UI APIs

Import / export enable/disable

UI.disableAnnotationExport();   // useViewer.setAnnotationExport(false)
UI.enableAnnotationExport();    // useViewer.setAnnotationExport(true)
UI.disableAnnotationImport();   // useViewer.setAnnotationImport(false)
UI.enableAnnotationImport();    // useViewer.setAnnotationImport(true)

These toggle the annotation.isAnnotationExport / annotation.isAnnotationImport flags in the viewer store, controlling whether the UI offers import/export of annotations.

Author / user

UI.setCurrentUser('alice');     // falls back to 'Guest'
UI.setAnnotator('alice');       // same store action as setCurrentUser
UI.setAuthor('alice');          // empty string if falsy
UI.setHighlightLink(true);      // toggle link highlighting

Annotation popup

The annotation context menu is customizable — see Popups.

Core bridge (annotation surface)

The core bridge (src/core/) exposes the engine's annotation APIs on instance.Core:

Function	Purpose
getAnnotationsList	List annotations.
getAnnotationManager	Get the annotation manager.
getAnnotationHistoryManager	Get the undo/redo history manager.
importAnnotations / exportAnnotations	XFDF/JSON import/export.
exportXfdf / saveAnnotations	Save annotation data.
removeAllAnnotations	Clear all annotations.
selectAnnotation / jumpToAnnotation	Selection & navigation.
setAnnotationStyles	Update annotation styles.
addAnnotationImage	Add an image annotation.
handleReplyAnnotation	Reply threads.
setUnselectableAnnotationTypes / getUnselectableAnnotationTypes	Selection control.
enableAutoSelectOnCreate / disableAutoSelectOnCreate	Auto-select on creation.
updateViewWithColorIndex	Color-index view update.
showPopup / handlePopup	Popup control.
setAnnotator	Set the annotator name in the engine.
getDynamicStampPreview / getStampRect / handleStamp	Stamp helpers.
setHighlightLink / setHighlightForm	Highlight toggles.

Annotation state in the UI

The document store mirrors annotation state for the UI:

• annotations — array (wrapped in shallowReactive via initAnnotations), managed by page index.
• selectedAnnotation / selected — the currently selected annotation.
• annotationsCount — count (formatted as "N annotation(s)" by the getAnnotationsCount getter).
• getAllAnnotations getter — groups annotations by page index, filtering by a type allow-list and excluding replies.
• propertyPanel — the property-panel model for the selected annotation/form field.

initAnnotations / setAnnotations(annotation, type) manage the array by page index (add/delete/update). The store pushes changes into the engine — for example, setActiveToolColor writes the color and calls core.setTool.

Permission checks

helpers/annotationPermissions.js exposes canCopyAnnotations({ isReadOnly, isUserAdmin, currentAuthor, annotations }):

• false if read-only.
• true if the user is an admin.
• Otherwise requires every annotation's author to equal currentAuthor.

Examples

Disable annotation export and set the author

UI.disableAnnotationExport();
UI.setAuthor('alice');

Export annotations via the bridge

const xfdf = await instance.Core.exportXfdf();

List annotations

const annotations = instance.Core.getAnnotationsList();

Related

• Tools — creating annotations.
• Popups — the annotation context menu.
• Signatures — signature annotations.
• Stamps — stamp annotations.
• Core Bridge