What namespace is IFormFieldAnnotation defined in?

IFormFieldAnnotation is in the IronSoftware.Forms namespace, shipped in IronPdf.dll. It extends IFormFieldAnnotationObject for geometry (X, Y, Width, Height) and IPdfDocumentObject for document attachment. The concrete class FormFieldAnnotation implements it; instances are read from the Annotations property on a form field, which is what a developer receives when inspecting widget-level annotation data.

What implements IFormFieldAnnotation?

The concrete class FormFieldAnnotation in the IronSoftware.Forms namespace implements IFormFieldAnnotation. Instances are read from the Annotations property on a form field (typed as List of IFormFieldAnnotation), not constructed directly. Form field classes such as TextFormField, CheckboxFormField, RadioFormField, ComboboxFormField, SignatureFormField, and ImageFormField expose this collection but do not themselves implement IFormFieldAnnotation.

What is the difference between IFormFieldAnnotation and IFormField?

IFormField is the contract for a fillable form field as a whole, with Name, Value, ReadOnly, and field-level behavior. IFormFieldAnnotation is the contract for one on-page widget belonging to that field, with AppearanceState, AnnotationFlags, Javascript, and geometry. A single IFormField can own multiple IFormFieldAnnotation instances, which is how radio button groups expose their per-option widgets.

What is the difference between IFormFieldAnnotation and IFormFieldAnnotationObject?

IFormFieldAnnotationObject is the geometry-only base contract: X, Y, Width, Height. IFormFieldAnnotation extends it and adds the annotation surface: AnnotationFlags, Appearances, AppearanceState, FormField, Javascript, and OnAppearance. Code that needs only position can accept the base; code that needs appearance state or the parent field backreference should accept IFormFieldAnnotation.

Interface IFormFieldAnnotation

Document form field annotation

Inherited Members

IFormFieldAnnotationObject.X

IFormFieldAnnotationObject.Y

IFormFieldAnnotationObject.Width

IFormFieldAnnotationObject.Height

IPdfDocumentObject.Client

Namespace: IronSoftware.Forms

Assembly: IronPdf.dll

Syntax

public interface IFormFieldAnnotation : IFormFieldAnnotationObject, IPdfDocumentObject, IPdfDocumentObject, IDocumentObject

When you inspect or edit a single on-page widget annotation belonging to a fillable PDF form field in IronPDF, IFormFieldAnnotation is the contract you read it through. A single form field can own multiple annotations across pages, so each annotation carries its own appearance state, flags, and optional JavaScript hook while sharing a parent field through the FormField property. Geometry (X, Y, Width, Height) is inherited from IFormFieldAnnotationObject.

Widget-level access becomes necessary whenever a form must be inspected or edited per page rather than per field. Radio button groups, for example, surface their option widgets through the Annotations collection on the parent form field, where each entry exposes an AppearanceState such as Yes or Off that decides which radio in the group is currently selected. Per-page rendering audits, appearance customization, and form-flattening pipelines all read against this contract.

Most everyday access is through the Annotations property on a form field, which returns List<IFormFieldAnnotation>. The declared surface on this interface adds AnnotationFlags (a PdfAnnotationFlags value), Appearances (the list of named appearances the annotation defines), AppearanceState (which named appearance is active), FormField (the parent IFormFieldObject backreference), Javascript (an action script the annotation runs on interaction), and OnAppearance (the name of the appearance shown when the annotation is selected). The concrete implementor is FormFieldAnnotation; annotations are obtained from a loaded field, not constructed. For a worked example that reads a field's widgets and writes its value, see the fill and edit PDF forms how-to.

using IronPdf;
using IronSoftware.Forms;

PdfDocument pdf = PdfDocument.FromFile("application.pdf");

// Radio groups expose their option widgets as a List<IFormFieldAnnotation>.
IFormField radioGroup = pdf.Form.FindFormField("Shipping");
foreach (IFormFieldAnnotation annotation in radioGroup.Annotations)
{
    // X, Y, Width, Height come from IFormFieldAnnotationObject.
    // AppearanceState identifies which radio option this widget represents.
    System.Console.WriteLine(
        $"option={annotation.AppearanceState} at ({annotation.X},{annotation.Y})");
}

// Select the "Express" radio by assigning to the parent field's Value.
radioGroup.Value = "Express";
pdf.SaveAs("application-filled.pdf");

For the field-level contract that owns this annotation collection, see IFormField. For building forms from scratch, the create PDF forms how-to is the entry point.

Properties

AnnotationFlags

Annotation flags

Declaration

PdfAnnotationFlags AnnotationFlags { get; set; }

Property Value

Type	Description
PdfAnnotationFlags

Appearances

Annotation appearance names

Declaration

List<string> Appearances { get; }

Property Value

Type	Description
System.Collections.Generic.List<System.String>

AppearanceState

Current active appearance

Declaration

string AppearanceState { get; set; }

Property Value

Type	Description
System.String

FormField

Parent form

Declaration

IFormFieldObject FormField { get; set; }

Property Value

Type	Description
IFormFieldObject

Javascript

Javascript to execute when the annotation is interacted with

Declaration

string Javascript { get; set; }

Property Value

Type	Description
System.String

Remarks

See ISO 21757-1:2020 for an ECMAScript reference

OnAppearance

Name of the appearance which is active when this annotation is selected

Declaration

string OnAppearance { get; set; }

Property Value

Type	Description
System.String

Inherited members

Width

Height

Client