Annotation Models

All annotation-related methods in @embedpdf/engines use JavaScript objects that conform to the PdfAnnotationObject type definitions. These models can be imported directly from the @embedpdf/models package.


import { PdfAnnotationObject, PdfHighlightAnnoObject, PdfAnnotationSubtype } from '@embedpdf/models';

The Base Annotation Object

All annotation objects share a common set of base properties defined by the PdfAnnotationObjectBase interface.

Property	Type	Description
`id`	`string`	A unique UUID v4 identifier for the annotation. This is crucial for updating and deleting.
`type`	`PdfAnnotationSubtype`	An enum value indicating the kind of annotation (e.g., `HIGHLIGHT`, `INK`, `FREETEXT`).
`rect`	`Rect`	The bounding box of the annotation on the page.
`pageIndex`	`number`	The 0-based index of the page this annotation belongs to.
`contents`	`string`	(Optional) The text content of the annotation, often used for comments.
`author`	`string`	(Optional) The author of the annotation.
`modified`	`Date`	(Optional) The date the annotation was last modified.
`created`	`Date`	(Optional) The date the annotation was created.
`flags`	`PdfAnnotationFlagName[]`	(Optional) An array of flags like `'print'`, `'noZoom'`, etc.
`custom`	`any`	(Optional) A field to store any custom JSON-serializable data.

Specific Annotation Types

Different types of annotations extend the base object with properties specific to their function.

Markup Annotations

These annotations are used to mark up existing content on the page, typically text.

Highlight (`PdfHighlightAnnoObject`)

Used for highlighting text.


export interface PdfHighlightAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.HIGHLIGHT;
  color: string;      // e.g., '#FFFF00'
  opacity: number;    // 0.0 to 1.0
  segmentRects: Rect[]; // An array of rectangles covering the highlighted text segments.
}

Underline (`PdfUnderlineAnnoObject`)

Used for underlining text.


export interface PdfUnderlineAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.UNDERLINE;
  color: string;
  opacity: number;
  segmentRects: Rect[];
}

StrikeOut (`PdfStrikeOutAnnoObject`)

Used for striking through text.


export interface PdfStrikeOutAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.STRIKEOUT;
  color: string;
  opacity: number;
  segmentRects: Rect[];
}

Squiggly (`PdfSquigglyAnnoObject`)

Used for applying a squiggly underline to text.


export interface PdfSquigglyAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.SQUIGGLY;
  color: string;
  opacity: number;
  segmentRects: Rect[];
}

Shape & Drawing Annotations

These annotations add new vector shapes to the page.

Ink (`PdfInkAnnoObject`)

Used for freehand drawings.


export interface PdfInkAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.INK;
  inkList: { points: { x: number; y: number }[] }[]; // Array of strokes, each with an array of points.
  strokeWidth: number; // The thickness of the ink strokes.
  color: string;       // The color of the ink, e.g., '#FF0000'.
  opacity: number;     // 0.0 to 1.0
}

Square (`PdfSquareAnnoObject`)

Used for drawing a square or rectangle.


export interface PdfSquareAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.SQUARE;
  color: string; // Fill color
  strokeColor: string;
  strokeWidth: number;
  strokeStyle: PdfAnnotationBorderStyle;
  opacity: number;
}

Circle (`PdfCircleAnnoObject`)

Used for drawing a circle or ellipse.


export interface PdfCircleAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.CIRCLE;
  color: string; // Fill color
  strokeColor: string;
  strokeWidth: number;
  strokeStyle: PdfAnnotationBorderStyle;
  opacity: number;
}

Line (`PdfLineAnnoObject`)

Used for drawing a single straight line.


export interface PdfLineAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.LINE;
  linePoints: { start: Position; end: Position };
  lineEndings?: { start: PdfAnnotationLineEnding; end: PdfAnnotationLineEnding };
  strokeColor: string;
  strokeWidth: number;
  strokeStyle: PdfAnnotationBorderStyle;
  opacity: number;
}

Polyline (`PdfPolylineAnnoObject`)

Used for drawing a series of connected line segments.


export interface PdfPolylineAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.POLYLINE;
  vertices: Position[];
  lineEndings?: { start: PdfAnnotationLineEnding; end: PdfAnnotationLineEnding };
  strokeColor: string;
  strokeWidth: number;
  strokeStyle: PdfAnnotationBorderStyle;
  opacity: number;
}

Polygon (`PdfPolygonAnnoObject`)

Used for drawing a closed, multi-sided shape.


export interface PdfPolygonAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.POLYGON;
  vertices: Position[];
  color: string; // Fill color
  strokeColor: string;
  strokeWidth: number;
  strokeStyle: PdfAnnotationBorderStyle;
  opacity: number;
}

Text-Based Annotations

FreeText (`PdfFreeTextAnnoObject`)

Used for “Typewriter” style text boxes placed anywhere on the page.


export interface PdfFreeTextAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.FREETEXT;
  contents: string;
  fontSize: number;
  fontColor: string; // e.g., '#000000'
  fontFamily: PdfStandardFont;
  textAlign: PdfTextAlignment; // Left, Center, or Right
  backgroundColor?: string;
  opacity: number;
}

Text (`PdfTextAnnoObject`)

Used for “Sticky Note” style comments that appear as an icon on the page and reveal text when opened.


export interface PdfTextAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.TEXT;
  contents: string;
  color?: string;
  opacity?: number;
  icon?: PdfAnnotationIcon;
  state?: PdfAnnotationState;
  stateModel?: PdfAnnotationStateModel;
}

Other Annotation Types

Stamp (`PdfStampAnnoObject`)

Used for applying an image or predefined text stamp (e.g., “APPROVED”). The visual content for a new stamp is provided via the context parameter in createPageAnnotation.


export interface PdfStampAnnoObject extends PdfAnnotationObjectBase {
  type: PdfAnnotationSubtype.STAMP;
}

Annotation Models

The Base Annotation Object

Specific Annotation Types

Markup Annotations

Highlight (PdfHighlightAnnoObject)

Underline (PdfUnderlineAnnoObject)

StrikeOut (PdfStrikeOutAnnoObject)

Squiggly (PdfSquigglyAnnoObject)

Shape & Drawing Annotations

Ink (PdfInkAnnoObject)

Square (PdfSquareAnnoObject)

Circle (PdfCircleAnnoObject)

Line (PdfLineAnnoObject)

Polyline (PdfPolylineAnnoObject)

Polygon (PdfPolygonAnnoObject)