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.


<template>
  <PDFViewer
    :config="{
      annotation: {
        annotationAuthor: 'John Doe',
      }
    }"
  />
</template>

Programmatic Control

You can control the active tool and manage annotations programmatically.

Setting the Active Tool

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


<script setup lang="ts">
import { ref } from 'vue';
import { PDFViewer, type PluginRegistry, type AnnotationPlugin } from '@embedpdf/vue-pdf-viewer';
 
const registry = ref<PluginRegistry | null>(null);
 
const handleReady = (r: PluginRegistry) => {
  registry.value = r;
};
 
const activateHighlighter = () => {
  const annotationPlugin = registry.value?.getPlugin<AnnotationPlugin>('annotation')?.provides();
  annotationPlugin?.setActiveTool('highlight');
};
 
const activatePen = () => {
  const annotationPlugin = registry.value?.getPlugin<AnnotationPlugin>('annotation')?.provides();
  annotationPlugin?.setActiveTool('ink');
};
 
const deactivateTool = () => {
  const annotationPlugin = registry.value?.getPlugin<AnnotationPlugin>('annotation')?.provides();
  annotationPlugin?.setActiveTool(null);
};
</script>
 
<template>
  <PDFViewer @ready="handleReady" :config="{ src: '/doc.pdf' }" />
</template>

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.


<script setup lang="ts">
import { PDFViewer, type PluginRegistry } from '@embedpdf/vue-pdf-viewer';
 
const handleReady = (registry: PluginRegistry) => {
  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);
    } 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');
  });
};
</script>
 
<template>
  <PDFViewer @ready="handleReady" :config="{ src: '/doc.pdf' }" />
</template>

Importing and Exporting Annotations

You can export all annotations from a document and re-import them later. This is useful for saving annotation state to a backend or transferring annotations between sessions.

Exporting Annotations

exportAnnotations() returns a Task that resolves to an array of AnnotationTransferItem objects. Each item contains the annotation object and, for stamps, a ctx with the appearance data as an ArrayBuffer.


<script setup lang="ts">
import { ref } from 'vue';
import {
  PDFViewer,
  type PluginRegistry,
  type AnnotationPlugin,
  type AnnotationTransferItem,
} from '@embedpdf/vue-pdf-viewer';
 
const exported = ref<AnnotationTransferItem[] | null>(null);
 
const handleReady = (registry: PluginRegistry) => {
  const api = registry.getPlugin<AnnotationPlugin>('annotation')?.provides();
 
  api?.exportAnnotations().wait(
    (items) => {
      exported.value = items;
      console.log(`Exported ${items.length} annotations`);
    },
    (error) => console.error('Export failed', error),
  );
};
</script>

Importing Annotations

importAnnotations() accepts the same AnnotationTransferItem[] format returned by exportAnnotations(), making the round-trip seamless.


<script setup lang="ts">
api?.importAnnotations(exported.value);
</script>

For stamps, the ctx.data field accepts a raw ArrayBuffer containing PNG, JPEG, or PDF data — the engine detects the format automatically via magic bytes.

Adding Custom Stamp Tools

You can register custom stamp tools that place images with a single click. Access the annotation API in the @ready handler:


<script setup lang="ts">
import {
  PDFViewer,
  type PluginRegistry,
  type AnnotationPlugin,
  type AnnotationTool,
  PdfAnnotationSubtype,
  type PdfStampAnnoObject,
} from '@embedpdf/vue-pdf-viewer';
 
const handleReady = (registry: PluginRegistry) => {
  const api = registry.getPlugin<AnnotationPlugin>('annotation')?.provides();
 
  api?.addTool<AnnotationTool<PdfStampAnnoObject>>({
    id: 'stampCheckmark',
    name: 'Checkmark',
    interaction: { exclusive: true, cursor: 'crosshair' },
    matchScore: () => 0,
    defaults: {
      type: PdfAnnotationSubtype.STAMP,
      imageSrc: '/circle-checkmark.png',
      imageSize: { width: 30, height: 30 },
    },
    behavior: {
      showGhost: true,
      deactivateToolAfterCreate: true,
      selectAfterCreate: true,
    },
  });
};
</script>
 
<template>
  <PDFViewer @ready="handleReady" :config="{ src: '/doc.pdf' }" />
</template>
``