Annotations

The PDFViewer includes a powerful annotation system that supports highlights, ink drawings, shapes, and more. While the built-in toolbar provides a UI for these tools, you can also control them programmatically.

Configuration

You can configure annotation defaults like the author name using the annotation config object.


<PDFViewer
  config={{
    annotation: {
      annotationAuthor: 'John Doe',
      autoCommit: true, // Default: true - save changes to engine automatically
      selectAfterCreate: true // Select annotation after creating it
    }
  }}
/>

Programmatic Control

You can control the active tool and manage annotations programmatically.

Tools:

Log: Ready

Setting the Active Tool

Use setActiveTool to switch between tools. Pass null to switch back to the default selection cursor.


import { AnnotationPlugin } from '@embedpdf/react-pdf-viewer';
 
const registry = await viewerRef.current?.registry;
const annotationPlugin = registry.getPlugin<AnnotationPlugin>('annotation')?.provides();
 
// Activate Highlighter
annotationPlugin?.setActiveTool('highlight');
 
// Activate Pen (Ink)
annotationPlugin?.setActiveTool('ink');
 
// Deactivate tool (switch to selection mode)
annotationPlugin?.setActiveTool(null);

Common Tool IDs

Tool	ID	Description
Highlight	`'highlight'`	Text highlighter
Underline	`'underline'`	Text underline
Ink (Pen)	`'ink'`	Freehand drawing
Rectangle	`'square'`	Square/Rectangle shape
Circle	`'circle'`	Circle/Ellipse shape
Text	`'freeText'`	Free text box
Note	`'text'`	Sticky note

Listening for Changes

You can listen for annotation events (creation, deletion, updates) to sync with a backend or update your UI.


const registry = await viewerRef.current?.registry;
const annotationPlugin = registry.getPlugin('annotation').provides();
 
// Listen for creation, updates, and deletion
annotationPlugin.onAnnotationEvent((event) => {
  const { type, annotation, pageIndex } = event;
 
  if (type === 'create') {
    console.log('Created annotation:', annotation.id);
    // e.g. save to backend
  } else if (type === 'delete') {
    console.log('Deleted annotation:', annotation.id);
  }
});
 
// Listen for tool changes
annotationPlugin.onActiveToolChange(({ tool }) => {
  console.log('Active tool:', tool ? tool.name : 'Selection');
});