Class CheckboxFormField

Inheritance
System.Object
CheckboxFormField
Implements
IronSoftware.Abstractions.Pdf.IPdfDocumentObject
IronSoftware.Abstractions.IDocumentObject
Namespace: IronSoftware.Forms
Assembly: IronPdf.dll
Syntax
public class CheckboxFormField : Object, ICheckableFormField, IFormField, IFormFieldObject, IFormFieldAnnotationObject, IPdfDocumentObject, IPdfDocumentObject, IDocumentObject

Filling or reading a fillable PDF checkbox runs through CheckboxFormField, the concrete implementor of IFormField for that field type. The class carries the data of a single checkbox (its current value, the on-values defined by the PDF, and identifying name), the one-to-many annotation geometry that places the checkbox on the page (a single logical field can render as several widgets), and the methods that toggle its selected state.

A checkbox state is read or written through the inherited Value property, which is a string rather than a bool because a PDF checkbox can declare its own on-value. Assigning the source PDF's on-value (typically "Yes") checks the box, and assigning the static field CheckboxFormField.OffValue returns it to the off state. Typical scenarios include filling acknowledgement and consent checkboxes during onboarding workflows, mass-clearing boilerplate selections on templated forms, and reading back the checked state for downstream record-keeping.

Acquire an instance by calling FindFormField on the form-field collection of a loaded PdfDocument and casting the returned IFormField to CheckboxFormField. The headline members beyond Value and OffValue are the ICheckableFormField surface shared with RadioFormField and ComboboxFormField: Choices (the on-values defined by the PDF), SelectedIndex (the current selection into Choices), Select(int Index = -1) (sets the field to the value at that index and returns it), and Clear() (removes any selected value). Annotations is a List<IFormFieldAnnotation> because a single named checkbox can render multiple widgets across the page that all share one value. Checking and unchecking boxes on a loaded document is shown step by step in the edit PDF forms how-to.

using IronPdf;
using IronSoftware.Forms;

// Load the form and locate the checkbox by name.
PdfDocument pdf = PdfDocument.FromFile("application.pdf");
CheckboxFormField agreed = (CheckboxFormField)pdf.Form.FindFormField("AgreedToTerms");

// Check the box by assigning the on-value the PDF defines for this field.
// Choices[0] is the canonical on-value; "Yes" is the typical default.
if (!agreed.ReadOnly)
{
    agreed.Value = agreed.Choices.Count > 0 ? agreed.Choices[0] : "Yes";
}

// Uncheck a different box using the static OffValue rather than a string literal.
CheckboxFormField subscribe = (CheckboxFormField)pdf.Form.FindFormField("Newsletter");
subscribe.Value = CheckboxFormField.OffValue;

pdf.SaveAs("application-filled.pdf");

For the constructor path used when building checkboxes from scratch rather than editing an existing PDF, see the create PDF forms how-to. The interface that unifies every form-field type, including this one, is documented on the IFormField interface reference.

Constructors

CheckboxFormField(String, String, UInt32, Double, Double, Double, Double)

Create a new checkbox form field using the specified parameters

Declaration
public CheckboxFormField(string name, string value, uint page_index, double x, double y, double width, double height)
Parameters
Type Name Description
System.String name

Form name
System.String value

Form value
System.UInt32 page_index

Form page index
System.Double x

Form x-coordinate
System.Double y

Form y-coordinate
System.Double width

Form width
System.Double height

Form height

Fields

OffValue

Value which can be assigned to a checkbox to disable it

Declaration
public static string OffValue
Field Value
Type Description
System.String

Properties

Annotations

Form field annotations

Declaration
public List<IFormFieldAnnotation> Annotations { get; protected set; }
Property Value
Type Description
System.Collections.Generic.List<IFormFieldAnnotation>

Choices

Selection choices

Declaration
public List<string> Choices { get; }
Property Value
Type Description
System.Collections.Generic.List<System.String>

Client

Pdf client

Declaration
public IPdfClient Client { get; set; }
Property Value
Type Description
IronSoftware.Pdfium.IPdfClient

DefaultAppearance

Default appearance string

Declaration
public string DefaultAppearance { get; set; }
Property Value
Type Description
System.String

DocumentId

Declaration
public IDocumentId DocumentId { get; set; }
Property Value
Type Description
IronSoftware.Abstractions.Pdf.IDocumentId

FormFlags

Form field flags

Declaration
public PdfFormFieldFlags FormFlags { get; set; }
Property Value
Type Description
PdfFormFieldFlags

FormType

Form type

Declaration
public string FormType { get; }
Property Value
Type Description
System.String

FullName

Fully qualified name

Declaration
public string FullName { get; protected set; }
Property Value
Type Description
System.String

Height

Annotation height

Declaration
public double Height { get; set; }
Property Value
Type Description
System.Double

MaxLength

Maximum number of characters which can be specified in the value

Declaration
public int MaxLength { get; set; }
Property Value
Type Description
System.Int32

Name

Partial name

Declaration
public string Name { get; set; }
Property Value
Type Description
System.String

ObjNum

Declaration
public uint ObjNum { get; set; }
Property Value
Type Description
System.UInt32

ObjType

Object type

Declaration
public string ObjType { get; }
Property Value
Type Description
System.String

PageIndex

Declaration
public uint PageIndex { get; set; }
Property Value
Type Description
System.UInt32

ReadOnly

True if read-only

Declaration
public bool ReadOnly { get; set; }
Property Value
Type Description
System.Boolean

RichText

Form value using rich text

Declaration
public string RichText { get; set; }
Property Value
Type Description
System.String

SelectedIndex

Currently selected index

Declaration
public int SelectedIndex { get; set; }
Property Value
Type Description
System.Int32

Type

Pdf form field type

Declaration
public PdfFormFieldType Type { get; }
Property Value
Type Description
PdfFormFieldType

Value

Form value

Declaration
public string Value { get; set; }
Property Value
Type Description
System.String

Width

Annotation width

Declaration
public double Width { get; set; }
Property Value
Type Description
System.Double

X

Annotation X position

Declaration
public double X { get; set; }
Property Value
Type Description
System.Double

Y

Annotation y position

Declaration
public double Y { get; set; }
Property Value
Type Description
System.Double

Methods

Clear()

Clear any and all selected values

Declaration
public void Clear()

Select(Int32)

Select the value at the specified index

If no index is provided, selects the first value. If there are more than one options, throws an exception

Declaration
public string Select(int Index = -1)
Parameters
Type Name Description
System.Int32 Index
Returns
Type Description
System.String

Value at the selected index
Exceptions
Type Condition
System.Exception

No index was provided and there is more than one selectable option

SetDefaultFont(String, Int32, Color)

Set the default font to be used by this form field and any associated annotations

Declaration
public void SetDefaultFont(string FontName, int FontSize, Color FontColor)
Parameters
Type Name Description
System.String FontName

Font name with weight. Example "AdobeThai-Bold"
System.Int32 FontSize

Font size (whole integer such as 12 or 24)
System.Drawing.Color FontColor

Font color (only R, G, and B are used)
Remarks

This option may be overwritten by fonts applied to specific form field annotations

Implements

IronSoftware.Abstractions.Pdf.IPdfDocumentObject
IronSoftware.Abstractions.IDocumentObject