Adding annotations to a PDF document

Use annotations to add comments, markup, stamps, and links to PDF documents.

Common use cases include:

  • Review and approval workflows
  • Team collaboration and feedback
  • Programmatic document markup
  • Navigation links inside and outside a document
Download sample

How Nutrient helps

Nutrient Java SDK handles annotation structures and appearance generation.

The SDK handles:

  • Parsing annotation dictionaries and appearance streams
  • Managing annotation flags and border styles
  • Handling coordinate transformations and bounding box calculations
  • Complex annotation state management and reply chains

Complete implementation

This example adds several annotation types to a PDF:

package io.nutrient.Sample;


import io.nutrient.sdk.Document;
import io.nutrient.sdk.types.Color;
import io.nutrient.sdk.editors.PdfEditor;
import io.nutrient.sdk.editors.pdf.pages.PdfPageCollection;
import io.nutrient.sdk.editors.pdf.pages.PdfPage;
import io.nutrient.sdk.editors.pdf.annotations.PdfAnnotationCollection;
import io.nutrient.sdk.editors.pdf.annotations.PdfAnnotation;
import io.nutrient.sdk.editors.pdf.annotations.PdfTextAnnotation;
import io.nutrient.sdk.editors.pdf.annotations.PdfHighlightAnnotation;
import io.nutrient.sdk.editors.pdf.annotations.PdfUnderlineAnnotation;
import io.nutrient.sdk.editors.pdf.annotations.PdfStrikeOutAnnotation;
import io.nutrient.sdk.editors.pdf.annotations.PdfSquigglyAnnotation;
import io.nutrient.sdk.editors.pdf.annotations.PdfStampAnnotation;
import io.nutrient.sdk.editors.pdf.annotations.PdfLinkAnnotation;


public class AddAnnotationsToPdf {

Create the main method as the sample entry point:

    public static void main(String[] args) {

Open the document with try-with-resources, create an editor, and ensure one page exists:

        try (Document document = Document.open("input.pdf")) {
            PdfEditor editor = PdfEditor.edit(document);
            PdfPageCollection pages = editor.getPageCollection();


            if (pages.getCount() == 0) {
                pages.add(612.0f, 792.0f);
            }


            PdfPage page = pages.getFirst();
            PdfAnnotationCollection annotations = page.getAnnotationCollection();

annotations is bound to page = pages.getFirst(), so all annotations added through this collection are created on that first page.

Add a sticky note with position, author, subject, and contents.

In this sample:

  • The position is (100, 700).
  • The color is set to yellow with ARGB values.
            PdfTextAnnotation stickyNote = annotations.addStickyNote(
                100.0f, 700.0f,  // x, y
                "Test Author",
                "Test Subject",
                "This is a sticky note comment"
            );
            // Customize the color
            stickyNote.setColor(Color.fromArgb(255, 255, 255, 0));

Add text markup annotations: highlight, underline, strikeout, and squiggly.

Each annotation uses:

  • x, y, width, height for placement
  • Author and contents metadata
  • Optional color customization
            PdfHighlightAnnotation highlight = annotations.addHighlight(
                50.0f, 600.0f, 150.0f, 20.0f,  // x, y, width, height
                "Highlighter",
                "Highlighted text area"
            );
            highlight.setColor(Color.fromArgb(128, 255, 255, 0));


            PdfUnderlineAnnotation underline = annotations.addUnderline(
                50.0f, 550.0f, 150.0f, 20.0f,  // x, y, width, height
                "Underliner",
                "Underlined text area"
            );
            underline.setColor(Color.fromArgb(255, 0, 0, 255));


            PdfStrikeOutAnnotation strikeOut = annotations.addStrikeOut(
                50.0f, 500.0f, 150.0f, 20.0f,  // x, y, width, height
                "Striker",
                "Struck out text area"
            );
            strikeOut.setColor(Color.fromArgb(255, 255, 0, 0));


            PdfSquigglyAnnotation squiggly = annotations.addSquiggly(
                50.0f, 450.0f, 150.0f, 20.0f,  // x, y, width, height
                "Squiggler",
                "Squiggly underlined area"
            );
            squiggly.setColor(Color.fromArgb(255, 0, 128, 0));

Add a stamp annotation for status-style markup.

In this sample:

  • The position is (300, 600).
  • The size is 100 × 50.
  • The color is set to purple.
            PdfStampAnnotation stamp = annotations.addStamp(
                300.0f, 600.0f, 100.0f, 50.0f,  // x, y, width, height
                "Stamp Title",
                "Stamp contents"
            );
            // Customize the color
            stamp.setColor(Color.fromArgb(255, 128, 0, 128));

Add two link annotation types:

  • External URI link with setURI()
  • Internal page destination link with setDestination()

Even after adding a new page, annotations still points to the first page (pages.getFirst()), so the new link annotation is created on the original first page.

            PdfLinkAnnotation link = annotations.addLink(
                300.0f, 500.0f, 200.0f, 20.0f  // x, y, width, height
            );
            link.setURI("https://www.nutrient.io");


            pages.add(612.0f, 792.0f);
            PdfLinkAnnotation pageLink = annotations.addLink(
                300.0f, 450.0f, 200.0f, 20.0f  // x, y, width, height
            );
            pageLink.setDestination(2, 0.0f, 792.0f);

Iterate over annotations, inspect types, remove one by index, and then save:

Iteration includes existing annotations already present in the input PDF plus the annotations added in this sample, so the printed list can contain more items or types than the newly created annotations alone.

removeAt(0) removes whichever annotation is currently first on that page. If the input PDF already contains annotations, it may remove an existing annotation rather than one added in this sample.

            for (PdfAnnotation annot : annotations) {
                System.out.println("Annotation: " + annot.getClass().getSimpleName());
            }


            annotations.removeAt(0);


            editor.saveAs("output.pdf");
            editor.close();
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Conclusion

Use this workflow to add annotations:

  1. Open the document and create an editor.
  2. Access the page collection and ensure at least one page exists.
  3. Retrieve the annotation collection for the target page.
  4. Add sticky note annotations with author and comment metadata.
  5. Add text markup annotations (highlight, underline, strikeout, squiggly) with positioning and colors.
  6. Add stamp annotations for document status indication.
  7. Add link annotations for external URIs and internal page navigation.
  8. Iterate through annotations for processing or filtering.
  9. Remove annotations by index position.
  10. Save and close the editor.

For related annotation workflows, refer to the Java SDK guides.