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 .NET SDK handles PDF free text annotation structures and appearance generation. With the SDK, you don’t need to manually implement:

• 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 most of the complexity behind the scenes, letting you focus on your business logic.

Nutrient generates free text annotation appearance streams for you, but final rendering can still vary across PDF viewers (for example, Acrobat, Preview, and browser viewers). Validate output in your target viewers, and flatten annotations into page content as a final step if pixel-perfect consistency is required.

Complete implementation

Below is a complete working example that demonstrates adding free text annotations with various styles to a PDF. The following line sets up the C# application by importing the Nutrient namespace:

using Nutrient;

The Document.Open() call opens the PDF document. The using statement(opens in a new tab) ensures the document and editor are 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
{
    using Document document = Document.Open("input.pdf");
    using PdfEditor editor = PdfEditor.Edit(document);
    PdfPageCollection pages = editor.PageCollection;

    if (pages.Count == 0)
    {
        pages.Add(612.0f, 792.0f);
    }

    PdfPage page = pages.First ?? throw new InvalidOperationException("The document has no pages.");
    PdfAnnotationCollection annotations = page.AnnotationCollection;

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 the color isn’t set:

    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 Color property 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.Color = 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.Color = 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.Color = 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.Color = Color.FromArgb(255, 240, 240, 240);

The final code block saves the document with all free text annotations. The try-catch block handles potential errors using NutrientException:

    editor.SaveAs("output.pdf");
    Console.WriteLine("Successfully saved output.pdf");
}
catch (NutrientException e)
{
    Console.Error.WriteLine($"Error: {e.Message}");
    Environment.Exit(1);
}

Error handling

Nutrient .NET SDK handles errors with exception handling. The methods presented in this guide throw a NutrientException if a failure occurs. The using statements release the editor and document handles even when a step fails.

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 the Color property.
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 the document — the using statements release the native handles.

Nutrient handles free text annotation appearance stream generation and related low-level details, so you don’t need to build these structures manually. Final visual rendering can still vary across PDF viewers.