Where does IAnnotation live in the IronPDF API?

IAnnotation is in the IronPdf.Annotations namespace, shipped in IronPdf.dll. It is declared as a standalone public interface with no parent interfaces. Concrete classes such as TextAnnotation and LinkAnnotation implement IAnnotation; they are what a developer builds and attaches through pdf.Annotations.Add on the PdfAnnotationCollection.

What is the difference between IAnnotation and PdfAnnotation?

IAnnotation is a public interface on the write side of the annotation API, implemented by TextAnnotation and LinkAnnotation, and consumed by PdfAnnotationCollection. PdfAnnotation is a public abstract class on the read side, returned from PdfDocument.GetAnnotations as List of PdfAnnotation. The two hierarchies are separate. Use IAnnotation when building or accepting annotations to attach to a document. Inspect PdfAnnotation subclasses when enumerating annotations that already exist on a loaded PDF.

How do you attach an IAnnotation to a PDF?

Call pdf.Annotations.Add(annotation) on the PdfDocument. The Annotations property is read-only and returns a PdfAnnotationCollection, which derives from ObservableCollection of IAnnotation, so Add accepts any IAnnotation implementor. Add accepts one annotation at a time; loop over a list to attach multiple. After Add, the AnnotationIndex property on the instance switches from -1 to the assigned slot inside the document. Save the document once after all annotations have been added rather than after each one.

Interface IAnnotation

Q: What implements IAnnotation in IronPDF?

Two concrete classes implement IAnnotation: TextAnnotation for interactive sticky-note review comments, and LinkAnnotation for clickable hyperlink overlays. Both derive from PdfClientAccessor and live in the IronPdf.Annotations namespace. Code typed against IAnnotation works uniformly across these implementors, with a downcast to the concrete type only required when type-specific configuration is needed. The PdfAnnotation hierarchy returned by PdfDocument.GetAnnotations is a separate read-side type family and does not implement this interface.

PDF document annotation

Namespace: IronPdf.Annotations

Assembly: IronPdf.dll

Syntax

public interface IAnnotation

IAnnotation is the contract you build against when adding annotations to a PDF through the IronPDF write-side annotation API. It supplies the polymorphic surface used by the PdfAnnotationCollection exposed on every PdfDocument. Two concrete classes implement it: TextAnnotation for interactive sticky-note review comments, and LinkAnnotation for clickable hyperlink overlays. The read-side PdfAnnotation hierarchy returned by PdfDocument.GetAnnotations is a separate type family and does not implement this interface.

Code typed against IAnnotation works uniformly across the write-side annotation types, which is the value it adds to application code. A document review pipeline can build a mixed list of sticky notes and inline links, pass them through generic helpers, and only downcast when type-specific configuration is needed. The interface is also the contract that drives PdfAnnotationCollection, which derives from ObservableCollection<IAnnotation>, so iteration, enumeration, and LINQ over pdf.Annotations all return IAnnotation instances rather than concrete annotation types. To see the implementors put to work on a live document, follow the annotations how-to.

Most of the surface is shared positioning and visibility state. The members that carry everyday use of the contract are PageIndex (which page the annotation belongs to, get-only on the interface and therefore fixed at construction time on the implementor), Title (the popup header for sticky notes or the descriptive label for link annotations), Contents (the annotation body text), and Hidden (the visibility flag viewers honor when rendering the page). The placement quartet X, Y, Width, Height (or the combined Rectangle) controls on-page geometry, Color controls the icon tint where applicable, AnnotationIndex is the diagnostic slot that switches from -1 to the assigned index after the annotation is attached, and DocumentId is populated by IronPDF when the annotation joins a document. Attach any IAnnotation to a PdfDocument through pdf.Annotations.Add(...) on the PdfAnnotationCollection returned by the read-only Annotations property.

using IronPdf;
using IronPdf.Annotations;

// IAnnotation is the polymorphic write-side contract.
// Build a mixed list of sticky notes and links, then attach them through one entry point.
List<IAnnotation> markup = new()
{
    new TextAnnotation(pageIndex: 0, Title: "Legal Review", Contents: "Verify clause 4.3.")
    {
        X = 72, Y = 720, Width = 200, Height = 60, Hidden = false
    },
    new LinkAnnotation(pageIndex: 0)
    {
        X = 72, Y = 640, Width = 200, Height = 20,
        Title = "Reference", Contents = "Linked source spec"
    }
};

var pdf = PdfDocument.FromFile("contract.pdf");

foreach (IAnnotation note in markup)
{
    pdf.Annotations.Add(note);
    // After Add, note.AnnotationIndex switches from -1 to its assigned slot.
}

pdf.SaveAs("contract-marked-up.pdf");

A runnable version of this pattern lives in the annotations example. For details on the two concrete implementors, consult the TextAnnotation and LinkAnnotation class references.

Properties

AnnotationIndex

Annotation index (of a given page)

Declaration

int AnnotationIndex { get; set; }

Property Value

Type	Description
System.Int32

Color

Annotation color

Declaration

Color Color { get; set; }

Property Value

Type	Description
IronSoftware.Drawing.Color

Annotation contents

Declaration

string Contents { get; set; }

Property Value

Type	Description
System.String

DocumentId

Document identifier

Declaration

IDocumentId DocumentId { get; set; }

Property Value

Type	Description
IronSoftware.Abstractions.Pdf.IDocumentId

Height

Annotation height

Declaration

int Height { get; set; }

Property Value

Type	Description
System.Int32

Hidden

Annotation visibility status

Declaration

bool Hidden { get; set; }

Property Value

Type	Description
System.Boolean

PageIndex

Page index

Declaration

int PageIndex { get; }

Property Value

Type	Description
System.Int32

Rectangle

Declaration

Rectangle Rectangle { get; set; }

Property Value

Type	Description
IronSoftware.Drawing.Rectangle

Title

Annotation title

Declaration

string Title { get; set; }

Property Value

Type	Description
System.String

Width

Annotation width

Declaration

int Width { get; set; }

Property Value

Type	Description
System.Int32

X

Annotation X position

Declaration

int X { get; set; }

Property Value

Type	Description
System.Int32

Y

Annotation y position

Declaration

int Y { get; set; }

Property Value

Type	Description
System.Int32