EmbedPDF
DocsSveltePluginsAnnotation

Annotation Plugin

The Annotation Plugin provides a comprehensive framework for adding, editing, and managing annotations within a PDF document. It supports a wide range of common annotation types, including text markups (highlight, underline), free-hand drawings (ink), shapes (squares, circles), and more.

The plugin is built on an extensible “Tool” system, allowing you to define and customize different annotation behaviors and appearances.

Installation

This plugin has several dependencies that must be installed to handle user interactions and manage state. The history plugin is optional but recommended for undo/redo functionality.

npm install @embedpdf/plugin-annotation @embedpdf/plugin-interaction-manager @embedpdf/plugin-selection @embedpdf/plugin-history

Registration

Import AnnotationPluginPackage and its dependencies. It is crucial to register the dependencies before the annotation plugin itself.

import { createPluginRegistration } from '@embedpdf/core'
import { EmbedPDF } from '@embedpdf/core/svelte'
// ... other imports
import { InteractionManagerPluginPackage } from '@embedpdf/plugin-interaction-manager/svelte'
import { SelectionPluginPackage } from '@embedpdf/plugin-selection/svelte'
import { HistoryPluginPackage } from '@embedpdf/plugin-history/svelte'
import { AnnotationPluginPackage } from '@embedpdf/plugin-annotation/svelte'
 
const plugins = [
  // ... other essential plugins
  createPluginRegistration(DocumentManagerPluginPackage, { /* ... */ }),
  createPluginRegistration(RenderPluginPackage),
 
  // Register dependencies first
  createPluginRegistration(InteractionManagerPluginPackage),
  createPluginRegistration(SelectionPluginPackage),
  createPluginRegistration(HistoryPluginPackage),
 
  // Register and configure the annotation plugin
  createPluginRegistration(AnnotationPluginPackage, {
    // Optional: Set the author name for created annotations
    annotationAuthor: 'Jane Doe',
  }),
]

Usage

The plugin works by combining a UI component to render the annotations with a store to manage the annotation tools and state.

1. The <AnnotationLayer /> Component

This component is responsible for rendering all annotations and handling user interactions like creating, selecting, moving, and resizing. It must be placed inside the <Scroller />’s renderPage snippet and wrapped by a <PagePointerProvider> to correctly process pointer events.

Note that documentId is required for all components to link them to the correct document state.

<script lang="ts">
import { PagePointerProvider } from '@embedpdf/plugin-interaction-manager/svelte';
import { AnnotationLayer } from '@embedpdf/plugin-annotation/svelte';
 
let { documentId }: { documentId: string } = $props();
</script>
 
{#snippet renderPage(page)}
  <PagePointerProvider {documentId} pageIndex={page.pageIndex}>
    <RenderLayer {documentId} pageIndex={page.pageIndex} />
    <SelectionLayer {documentId} pageIndex={page.pageIndex} />
    <AnnotationLayer
      {documentId}
      pageIndex={page.pageIndex}
    />
  </PagePointerProvider>
{/snippet}
 
<Scroller {documentId} {renderPage} />

2. Building an Annotation Toolbar

The useAnnotation store provides all the necessary methods to control the plugin for a specific document. You can build a toolbar that allows users to select an “active tool” (like a pen or highlighter) and perform actions like deleting a selected annotation.

<script lang="ts">
import { useAnnotation } from '@embedpdf/plugin-annotation/svelte';
 
let { documentId }: { documentId: string } = $props();
const annotation = useAnnotation(() => documentId);
 
const deleteSelected = () => {
  const selection = annotation.provides?.getSelectedAnnotation();
  if (selection) {
    annotation.provides?.deleteAnnotation(selection.object.pageIndex, selection.object.id);
  }
};
</script>
 
<div>
  <button onclick={() => annotation.provides?.setActiveTool('highlight')}>Highlighter</button>
  <button onclick={() => annotation.provides?.setActiveTool('ink')}>Pen</button>
  <button onclick={deleteSelected} disabled={!annotation.state.selectedUid}>Delete</button>
</div>

3. Adding a Selection Menu

When an annotation is selected, you can display a contextual menu (e.g., for deleting, editing properties). Use the selectionMenu snippet on <AnnotationLayer />. This snippet receives props including the context object, which contains the selected annotation.

<script lang="ts">
import { AnnotationLayer, useAnnotation } from '@embedpdf/plugin-annotation/svelte';
 
let { documentId }: { documentId: string } = $props();
const annotation = useAnnotation(() => documentId);
 
const handleDelete = (pageIndex: number, id: number) => {
  annotation.provides?.deleteAnnotation(pageIndex, id);
};
</script>
 
<AnnotationLayer {documentId} pageIndex={page.pageIndex}>
  {#snippet selectionMenuSnippet({ selected, context, menuWrapperProps, rect })}
    {#if selected}
      <span style={menuWrapperProps.style} use:menuWrapperProps.action>
        <div 
          style:position="absolute"
          style:top="{rect.size.height + 8}px"
          style:pointer-events="auto"
          style:cursor="default"
        >
          <button onclick={() => handleDelete(context.annotation.object.pageIndex, context.annotation.object.id)}>
            Delete
          </button>
        </div>
      </span>
    {/if}
  {/snippet}
</AnnotationLayer>

The menuWrapperProps provides a style string and an action for your wrapper element—the style handles positioning relative to page rotation, while the action handles event propagation to prevent interaction conflicts with underlying layers.

Live Example

Try using the annotation tools below. Select a tool from the toolbar to start creating annotations. Click on an annotation to select it, and use the delete button or the contextual menu to remove it.

Default Annotation Tools

The plugin comes with a set of pre-configured tools. You can activate any of these tools by passing its id to the setActiveTool method.

Tool NameidDescription
HighlighthighlightCreates text highlight annotations.
UnderlineunderlineCreates text underline annotations.
StrikeoutstrikeoutCreates text strikeout annotations.
SquigglysquigglyCreates squiggly text underline annotations.
PeninkFree-hand drawing tool.
Ink HighlighterinkHighlighterFree-hand highlighter with a multiply blend mode.
CirclecircleDraws ellipse annotations.
SquaresquareDraws rectangle annotations.
LinelineDraws straight line annotations.
ArrowlineArrowDraws a straight line with an arrowhead.
PolylinepolylineDraws multi-segment lines.
PolygonpolygonDraws closed, multi-sided shapes.
Free TextfreeTextAdds a text box annotation.
ImagestampAdds an image stamp. Opens a file picker by default.

API Reference

Configuration (AnnotationPluginConfig)

OptionTypeDescription
annotationAuthorstringSets the author name for all created annotations. Default: 'Guest'
autoCommitbooleanIf true, annotation changes are automatically saved to the engine. Default: true
toolsAnnotationTool[]An array of custom annotation tools to add or override default tools.
colorPresetsstring[]A list of hex color strings to be used in a color picker UI.
deactivateToolAfterCreatebooleanIf true, the active tool is deselected after an annotation is created. Default: false
selectAfterCreatebooleanIf true, a newly created annotation is automatically selected. Default: true

Component: <AnnotationLayer />

The primary component for rendering and interacting with annotations.

PropTypeDescription
documentIdstring(Required) The ID of the document this layer belongs to.
pageIndexnumber(Required) The page index this layer corresponds to.
selectionOutlineColorstringThe color of the outline around a selected annotation. Default: '#007ACC'
selectionMenuSnippet(Optional) A snippet to render a contextual menu when an annotation is selected.

Snippet: selectionMenu

PropTypeDescription
contextobjectThe selection context containing the annotation object.
selectedbooleantrue if an annotation is currently selected.
menuWrapperPropsMenuWrapperPropsAn object containing style: string for positioning and action: Action to attach to your wrapper element via use:menuWrapperProps.action.
rectRectThe bounding box of the selected annotation.

Store: useAnnotation(documentId)

Connects your components to the annotation plugin’s state and methods for a specific document.

Parameters

ParameterTypeDescription
documentId() => stringA getter function that returns the document ID to track.

Returns

PropertyTypeDescription
providesAnnotationScope | nullAn object with methods to control the plugin, or null if not ready.
stateAnnotationStateReactive state object containing properties like activeToolId, selectedUid.

AnnotationScope Methods

A selection of key methods available on the provides object:

MethodDescription
setActiveTool(toolId)Activates an annotation tool (e.g., 'ink', 'highlight'). Pass null to deactivate.
getActiveTool()Returns the currently active AnnotationTool object, or null.
addTool(tool)Registers a new custom AnnotationTool.
createAnnotation(..)Programmatically creates a new annotation on a page.
updateAnnotation(..)Updates the properties of an existing annotation.
deleteAnnotation(..)Deletes an annotation from a page.
selectAnnotation(..)Programmatically selects an annotation.
getSelectedAnnotation()Returns the currently selected TrackedAnnotation object, or null.
importAnnotations(..)Imports an array of annotations into the viewer.
commit()Manually saves all pending annotation changes to the PDF document.
onStateChange(cb)Subscribes to any change in the annotation state.
onAnnotationEvent(cb)Subscribes to events like annotation creation, updates, or deletion.
Last updated on December 5, 2025
ThumbnailSelection

Need Help?

Join our community for support, discussions, and to contribute to EmbedPDF's development.

GitHub DiscussionsDiscord CommunitySupport Development