PDF Annotations: Types and Usage

← Back to Blog

What Are PDF Annotations?

PDF annotations are graphical or interactive objects that are overlaid on top of a page's content stream without modifying the underlying content itself. They appear above the text, images, and graphics of the page and can be shown or hidden, printed or suppressed, and edited or deleted independently of the document's base content.

Annotations serve a wide range of purposes. In document review workflows they carry comments, questions, and change requests from reviewers back to authors. In technical drawings they mark dimensions and notes. In legal documents they can highlight disputed passages. In fillable forms, the form fields themselves — text boxes, checkboxes, radio buttons, and so on — are implemented as a specialised category of annotation called widget annotations.

The PDF specification (ISO 32000) defines a comprehensive annotation model that has been extended over successive PDF versions, and Acrobat has supported rich annotation features for decades.

How Annotations Are Stored in PDF

Each page in a PDF document has an /Annots array in its page dictionary that lists references to all annotations on that page:

<< /Type /Page
   /MediaBox [0 0 612 792]
   /Contents 10 0 R
   /Annots [20 0 R 21 0 R 22 0 R]
>>

Each annotation is an independent dictionary object. Every annotation dictionary must include:

• /Type /Annot — identifies the object as an annotation
• /Subtype — the specific annotation type (e.g. /Text, /Highlight, /Stamp)
• /Rect — a rectangle defining the annotation's bounding box on the page

Most annotations also carry optional but commonly used keys: /Contents (the annotation's text content), /M (modification date), /T (the author's name), /P (reference to the parent page), /C (colour), /CA (opacity), /F (flags controlling printing, hidden state, read-only, etc.), and /Popup (a reference to a pop-up annotation that displays the comment text).

Appearance Streams

The visual rendering of an annotation is defined by its appearance stream, stored in the /AP dictionary. An appearance stream is a small PDF content stream describing exactly how the annotation should look. The /AP dictionary can hold three streams: /N (normal), /R (rollover/hover), and /D (down/pressed), though only /N is required for most annotation types.

When Acrobat displays a stamp, a rubber-stamp-style graphic is stored in its /N appearance stream as a Form XObject. This makes the visual appearance fully self-contained within the PDF and ensures consistent rendering across different viewers.

Types of PDF Annotations

Text (Sticky Notes)

Subtype /Text. The most familiar annotation type — a small icon (by default a speech bubble or note icon) that expands into a pop-up window when clicked, showing the comment text. Text annotations are the primary vehicle for reviewer comments in document review workflows.

Markup Annotations: Highlights, Underlines, and Strikethroughs

The subtypes /Highlight, /Underline, /Squiggly, and /StrikeOut are text-markup annotations. They use a /QuadPoints array to define a series of quadrilaterals that follow the geometry of selected text, even across line breaks. This allows precise alignment with individual words or phrases rather than just a rectangular bounding box.

Stamps

Subtype /Stamp. Stamp annotations display a graphical overlay that resembles a rubber stamp impression. Acrobat ships with a library of built-in stamps (APPROVED, CONFIDENTIAL, DRAFT, FINAL, etc.) and allows users to create custom stamps from any PDF page, image, or even a dynamic stamp generated via JavaScript that automatically embeds the reviewer's name and a timestamp.

Free Text

Subtype /FreeText. Free text annotations — also called typewriter annotations — render text directly on the page at a specified location and are always visible without needing to be clicked. They support font, size, colour, and alignment properties. Callout annotations (a variant with a leader line from the text box to a point on the page) are also free text annotations with an additional /CL (callout line) key.

Ink Annotations

Subtype /Ink. Ink annotations represent freehand drawings — strokes made with a mouse, stylus, or touch input. The annotation stores the path as an array of arrays of points (/InkList), where each inner array is a separate ink stroke. Ink annotations are commonly used on tablets and touch-enabled devices for handwritten signatures or freehand markup.

Shape Annotations

The subtypes /Square, /Circle, /Line, /PolyLine, and /Polygon represent geometric shapes. Line annotations can carry arrow heads (via the /LE leader end style array). These are widely used in engineering and technical review for dimension marking and callout arrows.

File Attachment Annotations

Subtype /FileAttachment. These embed a file directly within the PDF, displayed as a paperclip or other icon. The attached file can be any format — another PDF, a spreadsheet, a source data file — and can be extracted by the reader. This is distinct from PDF-level embedded files (in the /EmbeddedFiles name tree), which are document-level attachments not tied to a page location.

Sound and Movie Annotations

Subtypes /Sound and /Movie embed audio and video content. These are legacy annotation types; modern rich media embedding in PDF uses the /RichMedia annotation type introduced in PDF 1.7 Extension Level 3 and formalised in PDF 2.0, which supports HTML5 and a broader range of media formats.

Widget Annotations (Form Fields)

Subtype /Widget. Widget annotations implement interactive form fields. They are linked to AcroForm field dictionaries in the document's /AcroForm structure. Though technically annotations, widgets are usually managed through Acrobat's form editing tools rather than the annotation tools, and they behave differently — they hold values, have validation scripts, and participate in form submission.

Review Workflows with Annotations

Acrobat supports two primary collaborative review modes:

Shared Review

In a shared review, Acrobat publishes the document to a shared location (originally a network folder or SharePoint, and more recently Adobe Document Cloud). Reviewers open the document, add their annotations, and publish them to the shared repository. All participants can see each other's comments in real time, reply to comments, and mark comments as resolved. This is the preferred workflow for teams needing to see all feedback together.

Email-Based Review

In an email-based review, the initiator sends the PDF via email to reviewers, who return their annotated copies. The initiator then uses Comments > Manage Comments > Import (or the comment import functionality in Acrobat) to merge all annotations from the returned copies into a single master document. This workflow does not require a shared server but can be cumbersome when consolidating many review copies.

Flattening Annotations

Flattening an annotation merges it permanently into the page's content stream, after which it can no longer be edited, deleted, or hidden separately from the page content. Flattening is necessary when:

• Sending a document to a printer or RIP that may not correctly render annotations
• Finalising a document so that markup cannot be altered by subsequent recipients
• Reducing file size by removing the separate annotation data structures
• Archiving a reviewed document with comments permanently embedded

Acrobat provides a Print Production flatten tool, and flattening can also be triggered via Acrobat JavaScript using the flattenPages() method or the Flatten tool in the Print Production panel. Once flattened, annotations cannot be recovered without reverting to an earlier version of the document.

Printing Annotations

Each annotation has a set of flags in its /F key that control printing behaviour. The Print flag (bit 3) determines whether the annotation appears in printed output. By default, most annotations have the Print flag set, so they appear in print. However, an annotation can be configured as screen-only (Print flag cleared) or print-only (Hidden flag set, Print flag set).

In Acrobat's Print dialog, the Comments and Forms dropdown lets you choose between printing the document only, the document with comments and markups, or form fields. For precise control over which annotations print, you can use JavaScript to iterate through annotations and selectively set or clear print flags before printing.

Acrobat JavaScript for Annotations

The Acrobat JavaScript API provides comprehensive access to annotations through the Doc and Page objects. Key methods include:

// Get all annotations on a page
var annots = this.getAnnots({nPage: 0});

// Create a new text (sticky note) annotation
var annot = this.addAnnot({
  type: "Text",
  page: 0,
  rect: [100, 700, 130, 730],
  author: "Reviewer",
  contents: "Please check this figure.",
  noteIcon: "Comment"
});

// Change an annotation's colour to red
annot.strokeColor = color.red;

// Delete all annotations on page 0
if (annots) {
  for (var i = 0; i < annots.length; i++) {
    annots[i].destroy();
  }
}

JavaScript can be used to automate annotation reporting (exporting comment data to FDF or XFDF), validate that all comments have been resolved before a document is finalised, apply bulk formatting changes to existing annotations, or create annotations programmatically as part of a document generation pipeline.

For more on leveraging Acrobat JavaScript for PDF automation, see our article on Introduction to Acrobat JavaScript.