What Are PDF Annotations? Understanding Their Types and Uses

This article was first published in January 2018 and was updated in June 2024.

This article will delve into the world of PDF annotations, discussing what they are, the various types defined by the PDF specification, and how they’re represented within a PDF document. It’ll also explain how PSPDFKit simplifies working with these annotations through an intuitive annotation model.

Content displayed as a PDF page isn’t suitable for easy editing, but the PDF specification defines a comprehensive set of objects that can be added to PDF pages without changing the page content. These objects are called annotations, and their purpose ranges from marking up page content to implementing interactive features such as forms.

PDF viewers usually allow the creation and editing of various annotation types, e.g. text highlights, notes, lines, or shapes. Regardless of the annotation types that can be created, PDF viewers conforming to the PDF specification should also support rendering for all annotation types.

PDF Annotation Types

The PDF specification defines two categories for annotations:

• Markup annotations — Primarily used to mark up the content of a PDF document.

• Non-markup annotations — Used for other purposes, including interactive forms and multimedia.

Text Markup Annotations

The simplest types of markup annotations are text markup annotations for marking up page text. These include text highlight, underline, or strikeout annotations.

PSPDFKit enhances these basic tools by allowing users to customize colors, adjust line thickness, and manage annotation styles through an intuitive interface.

Drawing Annotations

Various drawing annotations can be applied on top of a PDF page, including:

• Square and circle annotations — For drawing squares/rectangles and circles/ellipses.

• Line annotations — For drawing straight lines.

• Polygon and polyline annotations — For drawing polygonal lines.

• Ink annotations — For freeform drawing and connecting points into Bézier curves.

All of these support the usual drawing properties such as color, line thickness, fill color (for filled shapes), or line styles (e.g. dotted, dashed).

PSPDFKit’s robust annotation system makes it easy to create and manipulate these shapes with customizable properties like color, line styles, and fill options.

Stamp Annotations

Stamp annotations can be used when simple shapes drawn with drawing annotations aren’t sufficient — for example, when you want to draw a complex raster or vector image.

PSPDFKit even supports enhanced stamps that can be saved in the browser’s local storage for repeated use, and that can be customized to include user-specific information like IDs or timestamps.

Text Annotations

Two annotation types can be used to add notes to the page:

• Text annotations for adding sticky notes

• Free-text annotations for adding a floating text box

PSPDFKit’s annotation tools provide rich text formatting options, such as font selection, text rotation, and justification, allowing for greater flexibility and clarity in note-taking.

Multimedia Annotations

Multimedia annotations let you add interactive elements like audio, video, and even 3D models to your PDF documents. These annotations are crucial for creating engaging and informative content, particularly in educational or technical fields.

Widget Annotations

Widget annotations are used to implement interactive forms within PDFs. PSPDFKit supports a variety of form elements, including buttons, checkboxes, and combo boxes, enabling the creation of fully interactive PDF forms that can be easily filled out and submitted.

The PDF Annotation Model

A PDF document is a collection of data objects organized into a tree structure. The document tree is formed from dictionaries of key-value pairs that can contain other dictionaries as values. An example of another PDF object is a content stream that contains lists of drawing operations or binary image data.

The top-level dictionary in a PDF document contains a list of pages in the document. Each page is represented by its own dictionary that contains separate entries for page content and for annotations associated with the page. Similarly, annotations are also represented by their own dictionaries. Each annotation dictionary contains at least two keys:

• Rect specifies the rectangle where the annotation is going to be positioned on the page. This rectangle is in the PDF page coordinate system, which has its origin in the bottom-left corner of the page, with the x axis pointing to the right and the y axis pointing up. Read more in our coordinate space guide.

• Subtype specifies one of the supported annotation types.

The annotation type specifies which additional keys can be present in the annotation dictionary and which keys are required.

Below is an example of a page dictionary:

46 0 obj
<<
    /Type       /Page                       % Specifies that this dictionary defines a page.
    /Annots     [207 0 R, 208 0 R, 209 0 R] % Contains a list of references to annotation objects on this page.
    /Contents   501 0 R                     % Reference to page content stream.
    /MediaBox   [0, 0, 595, 842]            % Page dimensions.
    % Other page properties
>>

Here’s an example of a single annotation dictionary:

207 0 obj <<
    /Type       /Annot                               % Specifies that this dictionary defines an annotation.
    /Subtype    /Highlight                           % Specifies annotation type.
    /Rect       [52.9556, 728.343, 191.196, 743.218] % Annotation bounding box in page coordinates.
    /C          [1.0, 1.0, 0.0]                      % Annotation color.
>>

You can find all the details about how annotations are stored inside PDF documents in section 8.4 of Adobe’s PDF specification.

Appearance Streams

Annotations may contain properties that describe their appearance — such as annotation color or shape. However, these don’t guarantee that the annotation will be displayed the same in different PDF viewers. To solve this problem, each annotation can define an appearance stream that should be used for rendering the annotation. An appearance stream is a set of drawing commands that tells a PDF viewer precisely how to render an annotation (independent of the visual properties defined in the annotation’s dictionary). The PSPDFKit SDK allows you to parse and create appearance streams.

PSPDFKit Annotation Model

The PDF annotation model is quite complex. The PSPDFKit SDK provides a facade that exposes annotation dictionaries as regular objects of your programming language of choice. It hides implementation details and complex interactions between various annotation properties. This makes it easy for our customers to work with annotations without any prior knowledge of the PDF file format.

Advanced Features in PSPDFKit’s PDF Annotation Library

PSPDFKit’s PDF annotation library offers several advanced features that enhance the usability and flexibility of annotations:

• No Zoom Annotation — This feature ensures that annotations maintain a consistent size, regardless of the zoom level of the PDF. This is particularly useful for viewing complex documents, such as architectural plans, where clarity is crucial.

• Enhanced Stamps — Users can save stamps locally in their browser and customize them with specific user data, such as IDs or timestamps. This feature streamlines the process of adding frequently used stamps and ensures consistency across documents.

• Inspector Tool — PSPDFKit’s context-sensitive inspector tool allows users to fine-tune the appearance of annotations, including adjusting border colors, fill colors, opacity, and font settings. This level of control ensures that annotations are not only functional but also visually cohesive with the rest of the document.

Additional Resources

PSPDFKit offers a wealth of resources to help you master PDF annotations. Here are a few to get you started:

• Annotation guides — Detailed guides on how to work with annotations in PSPDFKit SDKs.

• Instant JSON reference — Learn more about PSPDFKit’s serialization format for annotations and forms.

• Annotations demo — Try our annotation features with this live demo.

Whether you’re building for web, mobile, or desktop, PSPDFKit’s PDF annotation library provides everything you need to enhance document collaboration and user interaction in your app.

FAQ

Here are a few frequently asked questions about annotations.

What Are PDF Annotations?

PDF annotations are objects added to a PDF document to provide additional information or interactive elements without altering the original content. They include highlights, notes, shapes, and multimedia elements.

How Do I Annotate a PDF?

To annotate a PDF, open a document in a PDF viewer or editor, select the desired annotation tool, and apply the annotation to the document. Save the document to preserve the changes.

How Do I Annotate a PDF Programmatically?

To annotate a PDF programmatically, use the annotation editing APIs provided by PSPDFKit SDKs, or import annotations in Instant JSON or XFDF formats.

What Types of Annotations Can Be Added to a PDF?

The PDF specification includes text markup annotations (highlights, underlines), drawing annotations (shapes, lines), stamp annotations, text annotations (sticky notes, text boxes), multimedia annotations (sound, video), and widget annotations (interactive forms).

Can All PDF Viewers Handle Annotations?

Most PDF viewers conforming to the PDF specification can render all types of annotations. However, the editing capabilities might vary between viewers.

What Is an Appearance Stream of a PDF Annotation?

An appearance stream is a set of drawing commands that defines how an annotation should be rendered in a PDF viewer, ensuring consistent appearance across different viewers.

How Do I Use No Zoom Annotation in PSPDFKit?

The no zoom annotation feature ensures that annotations remain a consistent size, regardless of the document’s zoom level. This can be especially helpful in technical fields where precision is required.

Can I Save and Reuse Custom Stamps in PSPDFKit?

Yes, with PSPDFKit, you can save custom stamps in the browser’s local storage for easy reuse. You can also customize these stamps to include user-specific information like IDs or timestamps.