Adding free text annotations to a PDF document

Adding free text annotations to PDFs programmatically enables teams to automate document labeling, build watermarking systems, and implement visible commenting workflows. Whether you’re adding approval stamps, creating document headers, building caption systems, or implementing visible review notes, the free text annotation API provides complete control over text positioning, styling, and background colors. Unlike sticky note annotations that display as icons, free text annotations render text content directly on the page for immediate visibility.

How Nutrient helps you achieve this

Nutrient Java SDK handles PDF free text annotation structures and appearance generation. With the SDK, you don’t need to worry about:

  • Parsing annotation dictionaries and text appearance streams
  • Managing font embedding and character encoding
  • Handling text layout and line breaking
  • Complex coordinate transformations and rotation matrices

Instead, Nutrient provides an API that handles all the complexity behind the scenes, letting you focus on your business logic.

Complete implementation

Below is a complete working example that demonstrates adding free text annotations with various styles to a PDF. The following lines set up the Java application. The package declaration and import statements bring in all the necessary classes from the Nutrient SDK:

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.PdfFreeTextAnnotation;


public class FreeTextAnnotations {

The main method defines the entry point that will contain the free text annotation creation logic:

    public static void main(String[] args) {

The Document.open() call opens the PDF document. The try-with-resources statement ensures the document is automatically closed when you’re done, preventing resource leaks. The following code creates a PDF editor, accesses the page collection, ensures at least one page exists by adding a letter-size page (612×792 points) if the document is empty, and retrieves the annotation collection from the first page:

        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();

The following code adds a basic free text annotation at coordinates (50, 650) with dimensions 250×50 points. The addFreeText() method takes position coordinates (x, y), dimensions (width, height), author name, text content, font family (“Arial”), font size (12 points), and text color. The black text color is created using ARGB values (255, 0, 0, 0). The background defaults to transparent when setColor() isn’t called:

            Color blackColor = Color.fromArgb(255, 0, 0, 0);
            PdfFreeTextAnnotation textBox = annotations.addFreeText(
                50.0f, 650.0f, 250.0f, 50.0f,  // x, y, width, height
                "Author",
                "This is a free text annotation that displays directly on the page.",
                "Arial",
                12.0f,
                blackColor
            );

The following code adds a warning annotation with a red text color (255, 0, 0) and a light yellow background (255, 255, 200). The setColor() method sets the annotation’s background color, creating a highlighted appearance. This pattern is useful for warnings, alerts, or emphasizing critical information:

            Color redColor = Color.fromArgb(255, 255, 0, 0);
            PdfFreeTextAnnotation warningText = annotations.addFreeText(
                50.0f, 580.0f, 250.0f, 40.0f,  // x, y, width, height
                "Reviewer",
                "WARNING: This section requires review before publication.",
                "Arial",
                14.0f,
                redColor
            );
            // Optionally set a background color
            warningText.setColor(Color.fromArgb(255, 255, 255, 200));

The following code adds a note-style annotation with dark blue text (0, 0, 128) and a light blue background (200, 220, 255). The annotation uses Times New Roman font at 11 points and has a larger height (70 points) to accommodate multiple lines of text. Note-style annotations are commonly used for editorial comments or contextual explanations:

            Color darkBlue = Color.fromArgb(255, 0, 0, 128);
            PdfFreeTextAnnotation noteText = annotations.addFreeText(
                50.0f, 480.0f, 250.0f, 70.0f,  // x, y, width, height
                "Editor",
                "Note: Consider adding more context to this paragraph. The reader may not be familiar with the terminology used here.",
                "Times New Roman",
                11.0f,
                darkBlue
            );
            // Optionally set a background color
            noteText.setColor(Color.fromArgb(255, 200, 220, 255));

The following code demonstrates adding multiple styled annotations for document markup workflows. The first annotation creates an APPROVED stamp with dark green text (0, 100, 0), a light green background (200, 255, 200), and larger font size (18 points) for prominence. The second annotation creates a footer-style note using Courier New font at 9 points with gray text (100, 100, 100) and a light gray background (240, 240, 240). The footer spans 500 points wide to accommodate metadata text:

            Color darkGreen = Color.fromArgb(255, 0, 100, 0);


            PdfFreeTextAnnotation approvedNote = annotations.addFreeText(
                350.0f, 670.0f, 200.0f, 30.0f,  // x, y, width, height
                "Approver",
                "APPROVED",
                "Arial",
                18.0f,
                darkGreen
            );
            // Optionally set a background color
            approvedNote.setColor(Color.fromArgb(255, 200, 255, 200));


            Color grayText = Color.fromArgb(255, 100, 100, 100);


            PdfFreeTextAnnotation footnote = annotations.addFreeText(
                50.0f, 50.0f, 500.0f, 50.0f,  // x, y, width, height
                "System",
                "Document last modified: 2024-01-15 | Review cycle: Annual",
                "Courier New",
                9.0f,
                grayText
            );
            // Optionally set a background color
            footnote.setColor(Color.fromArgb(255, 240, 240, 240));

The final code block saves the document with all free text annotations and closes the editor:

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

Conclusion

The free text annotation workflow consists of several key operations:

  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 basic free text annotations with font, size, and text color specifications.
  5. Add colored annotations with background colors for emphasis using setColor().
  6. Add note-style annotations with custom fonts and multiline text support.
  7. Add multiple styled annotations for comprehensive document markup (approvals, footers).
  8. Save and close the editor.

Nutrient handles free text annotation appearance streams and font embedding so you don’t need to understand PDF text rendering or manage character encoding manually.