modern-pdf-lib / PdfForm
Class: PdfForm
Defined in: src/form/pdfForm.ts:132
Represents a PDF document's interactive form (AcroForm).
Provides access to all form fields, bulk fill, and flatten operations.
Constructors
Constructor
new PdfForm(
fields,acroFormDict):PdfForm
Defined in: src/form/pdfForm.ts:142
Parameters
fields
PdfField[]
acroFormDict
Returns
PdfForm
Methods
createButton()
createButton(
name,page,rect,label?):PdfButtonField
Defined in: src/form/pdfForm.ts:648
Create a new push button and add it to the form.
Parameters
name
string
Field name.
page
unknown
The PdfPage where the widget appears.
rect
Widget rectangle {x, y, width, height}.
height
number
width
number
x
number
y
number
label?
string
Optional button caption.
Returns
The newly created button field.
createCheckbox()
createCheckbox(
name,page,rect):PdfCheckboxField
Defined in: src/form/pdfForm.ts:530
Create a new checkbox and add it to the form.
Parameters
name
string
Field name.
page
number
Page index (zero-based).
rect
[number, number, number, number]
Widget rectangle [x1, y1, x2, y2].
Returns
The newly created checkbox field.
createDropdown()
createDropdown(
name,page,rect,options):PdfDropdownField
Defined in: src/form/pdfForm.ts:555
Create a new dropdown and add it to the form.
Parameters
name
string
Field name.
page
number
Page index (zero-based).
rect
[number, number, number, number]
Widget rectangle [x1, y1, x2, y2].
options
string[]
The list of option strings.
Returns
The newly created dropdown field.
createListbox()
createListbox(
name,page,rect,options):PdfListboxField
Defined in: src/form/pdfForm.ts:685
Create a new listbox and add it to the form.
A listbox is a choice field (/FT /Ch) without the Combo flag, displaying a scrollable list of options.
Parameters
name
string
Field name.
page
unknown
The PdfPage where the widget appears.
rect
Widget rectangle {x, y, width, height}.
height
number
width
number
x
number
y
number
options
string[]
The list of option strings.
Returns
The newly created listbox field.
createRadioGroup()
createRadioGroup(
name,page,rects,options?):PdfRadioGroup
Defined in: src/form/pdfForm.ts:589
Create a new radio button group and add it to the form.
A radio group is a single field with multiple widget annotations, one per rectangle in rects. Each widget corresponds to an option; if options is supplied the n-th option labels the n-th widget, otherwise options default to "Option0", "Option1", etc.
Parameters
name
string
Field name.
page
unknown
The PdfPage where the widgets appear (unused for positioning in the low-level dict, but reserved for future page-level annotation linking).
rects
object[]
Array of widget rectangles {x, y, width, height}.
options?
string[]
Optional option labels (one per rect).
Returns
The newly created radio group.
createTextField()
createTextField(
name,page,rect):PdfTextField
Defined in: src/form/pdfForm.ts:507
Create a new text field and add it to the form.
Parameters
name
string
Field name.
page
number
Page index (zero-based) where the widget appears.
rect
[number, number, number, number]
Widget rectangle [x1, y1, x2, y2].
Returns
The newly created text field.
deleteXFA()
deleteXFA():
void
Defined in: src/form/pdfForm.ts:487
Remove the /XFA entry from the AcroForm dictionary, if present.
XFA (XML Forms Architecture) data can cause PDF viewers to use the XFA renderer instead of the standard AcroForm renderer, which is often undesirable. Removing /XFA forces viewers to fall back to the AcroForm fields.
After removing /XFA, /NeedAppearances is set to true so that the viewer knows it must generate appearances for the AcroForm fields (since XFA appearances are no longer available).
This method is a no-op if the AcroForm dictionary does not contain an /XFA entry.
Returns
void
fill()
fill(
values):void
Defined in: src/form/pdfForm.ts:413
Fill multiple fields at once.
Accepts a record where keys are field names and values are the field values to set. Strings map to text/dropdown/listbox values; booleans map to checkbox checked states.
Parameters
values
Record<string, string | boolean>
A mapping of field name to value.
Returns
void
Throws
If a field name is not found.
flatten()
flatten():
void
Defined in: src/form/pdfForm.ts:442
Flatten the form: burn field values into the page content streams and remove the interactive form structure.
After flattening, the document is no longer interactive — field values become static page content. This is done by:
- Generating appearance streams for all fields that lack them
- Removing the /AcroForm entry from the catalog
- Removing /Widget annotations from page /Annots arrays
Note: In this implementation, we mark the form as flattened by setting a flag and clearing the /Fields array. The appearance streams remain as page annotations will reference them.
Returns
void
getButton()
getButton(
name):PdfButtonField
Defined in: src/form/pdfForm.ts:369
Get a button field by name. Throws if the field is not found or is not a button.
Parameters
name
string
Returns
getCheckbox()
getCheckbox(
name):PdfCheckboxField
Defined in: src/form/pdfForm.ts:301
Get a checkbox field by name. Throws if the field is not found or is not a checkbox.
Parameters
name
string
Returns
getDropdown()
getDropdown(
name):PdfDropdownField
Defined in: src/form/pdfForm.ts:335
Get a dropdown field by name. Throws if the field is not found or is not a dropdown.
Parameters
name
string
Returns
getField()
getField(
name):PdfField|undefined
Defined in: src/form/pdfForm.ts:276
Get a field by name (partial or fully-qualified). Returns undefined if not found.
Parameters
name
string
Returns
PdfField | undefined
getFields()
getFields():
PdfField[]
Defined in: src/form/pdfForm.ts:268
Get all fields in the form.
Returns
PdfField[]
getListbox()
getListbox(
name):PdfListboxField
Defined in: src/form/pdfForm.ts:352
Get a listbox field by name. Throws if the field is not found or is not a listbox.
Parameters
name
string
Returns
getRadioGroup()
getRadioGroup(
name):PdfRadioGroup
Defined in: src/form/pdfForm.ts:318
Get a radio group by name. Throws if the field is not found or is not a radio group.
Parameters
name
string
Returns
getSignatureField()
getSignatureField(
name):PdfSignatureField
Defined in: src/form/pdfForm.ts:386
Get a signature field by name. Throws if the field is not found or is not a signature field.
Parameters
name
string
Returns
getTextField()
getTextField(
name):PdfTextField
Defined in: src/form/pdfForm.ts:284
Get a text field by name. Throws if the field is not found or is not a text field.
Parameters
name
string
Returns
hasXFA()
hasXFA():
boolean
Defined in: src/form/pdfForm.ts:468
Check whether the AcroForm dictionary contains XFA data.
XFA (XML Forms Architecture) data causes PDF viewers to use the XFA renderer instead of the standard AcroForm renderer. Use deleteXFA to remove it.
Returns
boolean
true if the form has an /XFA entry.
removeField()
removeField(
name):void
Defined in: src/form/pdfForm.ts:715
Remove a field from the form by name.
Removes the field from the internal field list, the name index, and the /Fields array in the AcroForm dictionary.
Parameters
name
string
The field name (partial or fully-qualified).
Returns
void
Throws
If no field with the given name exists.
toDict()
toDict(
registry):PdfDict
Defined in: src/form/pdfForm.ts:756
Serialize the form back to a PdfDict.
Updates /NeedAppearances if appearances need to be generated by the viewer.
Parameters
registry
Returns
fromDict()
staticfromDict(acroFormDict,resolver):PdfForm
Defined in: src/form/pdfForm.ts:169
Build a PdfForm from a parsed /AcroForm dictionary.
Traverses the /Fields array and resolves indirect references to construct the field tree, then flattens it into a list of concrete field instances.
Parameters
acroFormDict
The /AcroForm dictionary from the document catalog.
resolver
Function to resolve PdfRef to PdfObject.
Returns
PdfForm