Recogito PDF Annotator

A JavaScript library for PDF annotation, using PDF.js and the Recogito Text Annotator.

Also available: React wrapper

Installation

npm install @recogito/pdf-annotator

Quick Start

import { createPDFAnnotator } from '@recogito/pdf-annotator';

var anno = await createPDFAnnotator(
  document.getElementById('container');, 
  'compressed.tracemonkey-pldi-09.pdf'
);

// Load annotations from a file
anno.loadAnnotations('annotations.json');

// Listen to user events
anno.on('createAnnotation', annotation => {
  console.log('new annotation', annotation);
});     

Configuration Options

const anno = createPDFAnnotator(element, url, options);

Option	Type	Default	Description
annotatingEnabled	boolean	true	Enable or disable interactive creation of new annotations.
dismissOnNotAnnotatable	'NEVER' | 'ALWAYS' | function	'NEVER'	Controls whether the current selection is dismissed when clicking outside of annotatable content.
mergeHighlights	object	undefined	Merge adjacent highlights. Options: horizontalTolerance and verticalTolerance (in pixels)
selectionMode	'shortest' | 'all'	'shortest'	When the user selects overlapping annotations: select all or only the shortest.
style	HighlightStyleExpression	undefined	Custom styling function for highlights.
user	User	anonymous guest	Current user information, automatically added to created or updated annotations.

Annotator API

Properties

currentScale: number

The current numeric scale value of the PDF viewer.

console.log(anno.currentScale);

currentScaleValue: string

The current scale setting value of the PDF viewer.

console.log(anno.currentScaleValue); // e.g. 'page-fit'

Methods

The PDF annotator supports all the API methods of the underlying text annotator instance. The following additional methods are available:

setScale(size: PDFScale | number): void

Sets the PDF viewer scale.

anno.setScale(2);
anno.setScale('page-fit');

zoomIn(percentage? number): void

Zoom the PDF viewer by a given percentage (default: 10).

anno.zoomIn();

zoomOut(percentage? number): void

Zoom the PDF viewer out by a given percentage (default: 10).

anno.zoomOut();

Events

The PDF annotator supports all the events of the underlying text annotator instance.

Annotation Format

The PDF annotator adds additional properties to the annotation target selector.

{ 
  "id": "cd18fb18-b0e9-44f4-a11d-39a35f830fb4",
  "bodies": [],
  "target": {
    "selector": [{
      "quote": "We present a trace-based compilation technique",
      "start": 3589,
      "end": 3635,
      "pageNumber": 1,
      "quadpoints": [
        328.95,
        276.11,
        510.17,
        276.11,
        328.95,
        286.55,
        510.17,
        286.55
      ]
    }],
    "created": "2025-09-30T10:28:25.987Z",
    "updated": "2025-09-30T10:28:27.561Z"
  }
}

• pageNumber - the PDF page number where the annotation is located.

• quadPoints - the bounding box rectangle(s) of the annotation, in PDF quadpoint format.

Annotation Styling

The PDF annotator supports the same styling properties as the text annotator.

const anno = createPDFAnnotator(element, url, {
  style: (annotation, state, z) => {
    const hasTag = annotation.bodies.some(b => b.purpose === 'tagging');

    return {
      fill: hasTag ? '#ffeb3b' : '#bbdefb',
      fillOpacity: state.hovered ? 0.35 : 0.2,
      underlineColor: hasTag ? '#f57f17' : undefined,
      underlineThickness: 1
    }
  }
});

License

The Recogito Text Annotator is licensed under the BSD 3-Clause license.