Class: PDFForm

Represents the interactive form of a [[PDFDocument]].

Interactive forms (sometimes called AcroForms) are collections of fields designed to gather information from a user. A PDF document may contains any number of fields that appear on various pages, all of which make up a single, global interactive form spanning the entire document. This means that instances of [[PDFDocument]] shall contain at most one [[PDFForm]].

The fields of an interactive form are represented by [[PDFField]] instances.

Properties

acroForm

readonly acroForm: PDFAcroForm;

Defined in: src/api/form/PDFForm.ts:103

The low-level PDFAcroForm wrapped by this form.

doc

readonly doc: PDFDocument;

Defined in: src/api/form/PDFForm.ts:106

The document to which this form belongs.

Methods

createButton()

createButton(name): PDFButton;

Defined in: src/api/form/PDFForm.ts:592

Create a new button field in this [[PDFForm]] with the given name. For example:

const font = await pdfDoc.embedFont(StandardFonts.Helvetica)
const page = pdfDoc.addPage()

const form = pdfDoc.getForm()
const button = form.createButton('cool.new.button')

button.addToPage('Do Stuff', font, page)

An error will be thrown if a field already exists with the provided name.

Parameters

Parameter	Type	Description
`name`	`string`	The fully qualified name for the new button.

Returns

PDFButton

The new button field.

createCheckBox()

createCheckBox(name): PDFCheckBox;

Defined in: src/api/form/PDFForm.ts:622

Create a new check box field in this [[PDFForm]] with the given name. For example:

const font = await pdfDoc.embedFont(StandardFonts.Helvetica)
const page = pdfDoc.addPage()

const form = pdfDoc.getForm()
const checkBox = form.createCheckBox('cool.new.checkBox')

checkBox.addToPage(page)

An error will be thrown if a field already exists with the provided name.

Parameters

Parameter	Type	Description
`name`	`string`	The fully qualified name for the new check box.

Returns

PDFCheckBox

The new check box field.

createDropdown()

createDropdown(name): PDFDropdown;

Defined in: src/api/form/PDFForm.ts:652

Create a new dropdown field in this [[PDFForm]] with the given name. For example:

const font = await pdfDoc.embedFont(StandardFonts.Helvetica)
const page = pdfDoc.addPage()

const form = pdfDoc.getForm()
const dropdown = form.createDropdown('cool.new.dropdown')

dropdown.addToPage(font, page)

An error will be thrown if a field already exists with the provided name.

Parameters

Parameter	Type	Description
`name`	`string`	The fully qualified name for the new dropdown.

Returns

PDFDropdown

The new dropdown field.

createOptionList()

createOptionList(name): PDFOptionList;

Defined in: src/api/form/PDFForm.ts:682

Create a new option list field in this [[PDFForm]] with the given name. For example:

const font = await pdfDoc.embedFont(StandardFonts.Helvetica)
const page = pdfDoc.addPage()

const form = pdfDoc.getForm()
const optionList = form.createOptionList('cool.new.optionList')

optionList.addToPage(font, page)

An error will be thrown if a field already exists with the provided name.

Parameters

Parameter	Type	Description
`name`	`string`	The fully qualified name for the new option list.

Returns

PDFOptionList

The new option list field.

createRadioGroup()

createRadioGroup(name): PDFRadioGroup;

Defined in: src/api/form/PDFForm.ts:713

Create a new radio group field in this [[PDFForm]] with the given name. For example:

const font = await pdfDoc.embedFont(StandardFonts.Helvetica)
const page = pdfDoc.addPage()

const form = pdfDoc.getForm()
const radioGroup = form.createRadioGroup('cool.new.radioGroup')

radioGroup.addOptionToPage('is-dog', page, { y: 0 })
radioGroup.addOptionToPage('is-cat', page, { y: 75 })

An error will be thrown if a field already exists with the provided name.

Parameters

Parameter	Type	Description
`name`	`string`	The fully qualified name for the new radio group.

Returns

PDFRadioGroup

The new radio group field.

createTextField()

createTextField(name): PDFTextField;

Defined in: src/api/form/PDFForm.ts:747

Create a new text field in this [[PDFForm]] with the given name. For example:

const font = await pdfDoc.embedFont(StandardFonts.Helvetica)
const page = pdfDoc.addPage()

const form = pdfDoc.getForm()
const textField = form.createTextField('cool.new.textField')

textField.addToPage(font, page)

An error will be thrown if a field already exists with the provided name.

Parameters

Parameter	Type	Description
`name`	`string`	The fully qualified name for the new radio group.

Returns

PDFTextField

The new radio group field.

deleteXFA()

deleteXFA(): void;

Defined in: src/api/form/PDFForm.ts:151

Disconnect the XFA data from this [[PDFForm]] (if any exists). This will force readers to fallback to standard fields if the [[PDFDocument]] contains any. For example:

For example:

const form = pdfDoc.getForm()
form.deleteXFA()

Returns

void

fieldIsDirty()

fieldIsDirty(fieldRef): boolean;

Defined in: src/api/form/PDFForm.ts:938

Returns true is the specified field has been marked as dirty.

const form = pdfDoc.getForm()
const field = form.getField('foo.bar')
if (form.fieldIsDirty(field.ref)) console.log('Field is dirty')

Parameters

Parameter	Type	Description
`fieldRef`	`PDFRef`	The reference to the field that should be checked.

Returns

boolean

Whether or not the specified field is dirty.

flatten()

flatten(options?): void;

Defined in: src/api/form/PDFForm.ts:782

Flatten all fields in this [[PDFForm]].

Flattening a form field will take the current appearance for each of that field's widgets and make them part of their page's content stream. All form fields and annotations associated are then removed. Note that once a form has been flattened its fields can no longer be accessed or edited.

This operation is often used after filling form fields to ensure a consistent appearance across different PDF readers and/or printers. Another common use case is to copy a template document with form fields into another document. In this scenario you would load the template document, fill its fields, flatten it, and then copy its pages into the recipient document - the filled fields will be copied over.

For example:

const form = pdfDoc.getForm();
form.flatten();

Parameters

Parameter	Type
`options`	`FlattenOptions`

Returns

void

getButton()

getButton(name): PDFButton;

Defined in: src/api/form/PDFForm.ts:229

Get the button field in this [[PDFForm]] with the given name. For example:

const form = pdfDoc.getForm()
const button = form.getButton('Page1.Foo.Button[0]')

An error will be thrown if no field exists with the provided name, or if the field exists but is not a button.

Parameters

Parameter	Type	Description
`name`	`string`	A fully qualified button name.

Returns

PDFButton

The button with the specified name.

getCheckBox()

getCheckBox(name): PDFCheckBox;

Defined in: src/api/form/PDFForm.ts:249

Get the check box field in this [[PDFForm]] with the given name. For example:

const form = pdfDoc.getForm()
const checkBox = form.getCheckBox('Page1.Foo.CheckBox[0]')
checkBox.check()

An error will be thrown if no field exists with the provided name, or if the field exists but is not a check box.

Parameters

Parameter	Type	Description
`name`	`string`	A fully qualified check box name.

Returns

PDFCheckBox

The check box with the specified name.

getDefaultFont()

getDefaultFont(): PDFFont;

Defined in: src/api/form/PDFForm.ts:943

Returns

PDFFont

getDropdown()

getDropdown(name): PDFDropdown;

Defined in: src/api/form/PDFForm.ts:270

Get the dropdown field in this [[PDFForm]] with the given name. For example:

const form = pdfDoc.getForm()
const dropdown = form.getDropdown('Page1.Foo.Dropdown[0]')
const options = dropdown.getOptions()
dropdown.select(options[0])

An error will be thrown if no field exists with the provided name, or if the field exists but is not a dropdown.

Parameters

Parameter	Type	Description
`name`	`string`	A fully qualified dropdown name.

Returns

PDFDropdown

The dropdown with the specified name.

getField()

getField(name): PDFField;

Defined in: src/api/form/PDFForm.ts:211

Get the field in this [[PDFForm]] with the given name. For example:

const form = pdfDoc.getForm()
const field = form.getField('Page1.Foo.Bar[0]')

If no field exists with the provided name, an error will be thrown.

Parameters

Parameter	Type	Description
`name`	`string`	A fully qualified field name.

Returns

PDFField

The field with the specified name.

getFieldMaybe()

getFieldMaybe(name): PDFField | undefined;

Defined in: src/api/form/PDFForm.ts:191

Get the field in this [[PDFForm]] with the given name. For example:

const form = pdfDoc.getForm()
const field = form.getFieldMaybe('Page1.Foo.Bar[0]')
if (field) console.log('Field exists!')

Parameters

Parameter	Type	Description
`name`	`string`	A fully qualified field name.

Returns

PDFField | undefined

The field with the specified name, if one exists.

getFields()

getFields(): PDFField[];

Defined in: src/api/form/PDFForm.ts:168

Get all fields contained in this [[PDFForm]]. For example:

const form = pdfDoc.getForm()
const fields = form.getFields()
fields.forEach(field => {
  const type = field.constructor.name
  const name = field.getName()
  console.log(`${type}: ${name}`)
})

Returns

PDFField[]

An array of all fields in this form.

getOptionList()

getOptionList(name): PDFOptionList;

Defined in: src/api/form/PDFForm.ts:291

Get the option list field in this [[PDFForm]] with the given name. For example:

const form = pdfDoc.getForm()
const optionList = form.getOptionList('Page1.Foo.OptionList[0]')
const options = optionList.getOptions()
optionList.select(options[0])

An error will be thrown if no field exists with the provided name, or if the field exists but is not an option list.

Parameters

Parameter	Type	Description
`name`	`string`	A fully qualified option list name.

Returns

PDFOptionList

The option list with the specified name.

getRadioGroup()

getRadioGroup(name): PDFRadioGroup;

Defined in: src/api/form/PDFForm.ts:312

Get the radio group field in this [[PDFForm]] with the given name. For example:

const form = pdfDoc.getForm()
const radioGroup = form.getRadioGroup('Page1.Foo.RadioGroup[0]')
const options = radioGroup.getOptions()
radioGroup.select(options[0])

An error will be thrown if no field exists with the provided name, or if the field exists but is not a radio group.

Parameters

Parameter	Type	Description
`name`	`string`	A fully qualified radio group name.

Returns

PDFRadioGroup

The radio group with the specified name.

getSignature()

getSignature(name): PDFSignature;

Defined in: src/api/form/PDFForm.ts:331

Get the signature field in this [[PDFForm]] with the given name. For example:

const form = pdfDoc.getForm()
const signature = form.getSignature('Page1.Foo.Signature[0]')

An error will be thrown if no field exists with the provided name, or if the field exists but is not a signature.

Parameters

Parameter	Type	Description
`name`	`string`	A fully qualified signature name.

Returns

PDFSignature

The signature with the specified name.

getSignatureFields()

getSignatureFields(): SignatureField[];

Defined in: src/api/form/PDFForm.ts:405

Get all signature fields in this form, including both AcroForm signature fields and signature fields declared inside an XFA template. For example:

const form = pdfDoc.getForm()
const sigFields = form.getSignatureFields()
sigFields.forEach(({ name, source }) => {
  console.log(`${source} signature field: ${name}`)
})

Returns

SignatureField[]

An array of [[SignatureField]] describing every signature field, whether it originates from the AcroForm or from XFA.

getTextField()

getTextField(name): PDFTextField;

Defined in: src/api/form/PDFForm.ts:569

Get the text field in this [[PDFForm]] with the given name. For example:

const form = pdfDoc.getForm()
const textField = form.getTextField('Page1.Foo.TextField[0]')
textField.setText('Are you designed to act or to be acted upon?')

An error will be thrown if no field exists with the provided name, or if the field exists but is not a text field.

Parameters

Parameter	Type	Description
`name`	`string`	A fully qualified text field name.

Returns

PDFTextField

The text field with the specified name.

getXFAJavaScripts()

getXFAJavaScripts(): {
  event: string;
  field: string;
  script: string;
}[];

Defined in: src/api/form/PDFForm.ts:448

Get all JavaScript from this form's XFA template. XFA forms can contain JavaScript in <script> elements within the template XML. For example:

const form = pdfDoc.getForm()
const xfaScripts = form.getXFAJavaScripts()
xfaScripts.forEach(({ field, event, script }) => {
  console.log(`Field "${field}" on ${event}:`, script)
})

Note: load the document with preserveXFA: true. Prefer calling via [[PDFDocument.getXFAJavaScripts]] before [[PDFDocument.getForm]] when preserveXFA is not set, since getForm() strips XFA data otherwise.

Returns

{ event: string; field: string; script: string; }[]

An array of objects containing field names, events, and JavaScript code.

getXFASignatures()

getXFASignatures(): XFASignatureField[];

Defined in: src/api/form/PDFForm.ts:357

Get the signature fields declared inside this form's XFA template (if any).

Dynamic XFA forms declare signature fields inside the template XML rather than in the AcroForm /Fields array, so [[PDFForm.getSignature]] cannot see them. Each signature field carries a <signature> UI element that references a <manifest> describing which fields the signature covers (its FieldMDP scope). This method surfaces that information.

For example:

const form = pdfDoc.getForm()
form.getXFASignatures().forEach(({ field, manifest, refs }) => {
  console.log(`Signature "${field}" (manifest ${manifest}) covers`, refs)
})

Returns

XFASignatureField[]

An array of [[XFASignatureField]] objects, one per XFA signature field.

hasXFA()

hasXFA(): boolean;

Defined in: src/api/form/PDFForm.ts:136

Returns true if this [[PDFForm]] has XFA data. Most PDFs with form fields do not use XFA as it is not widely supported by PDF readers.

> pdf-lib does not support creation, modification, or reading of XFA > fields.

For example:

const form = pdfDoc.getForm()
if (form.hasXFA()) console.log('PDF has XFA data')

Returns

boolean

Whether or not this form has XFA data.

markFieldAsClean()

markFieldAsClean(fieldRef): void;

Defined in: src/api/form/PDFForm.ts:923

Mark a field as dirty. This will cause its appearance streams to not be updated by [[PDFForm.updateFieldAppearances]].

const form = pdfDoc.getForm()
const field = form.getField('foo.bar')
form.markFieldAsClean(field.ref)

Parameters

Parameter	Type	Description
`fieldRef`	`PDFRef`	The reference to the field that should be marked.

Returns

void

markFieldAsDirty()

markFieldAsDirty(fieldRef): void;

Defined in: src/api/form/PDFForm.ts:908

Mark a field as dirty. This will cause its appearance streams to be updated by [[PDFForm.updateFieldAppearances]].

const form = pdfDoc.getForm()
const field = form.getField('foo.bar')
form.markFieldAsDirty(field.ref)

Parameters

Parameter	Type	Description
`fieldRef`	`PDFRef`	The reference to the field that should be marked.

Returns

void

of()

static of(acroForm, doc): PDFForm;

Defined in: src/api/form/PDFForm.ts:99

> NOTE: You probably don't want to call this method directly. Instead, > consider using the [[PDFDocument.getForm]] method, which will create an > instance of [[PDFForm]] for you.

Create an instance of [[PDFForm]] from an existing acroForm and embedder

Parameters

Parameter	Type	Description
`acroForm`	`PDFAcroForm`	The underlying `PDFAcroForm` for this form.
`doc`	`PDFDocument`	The document to which the form will belong.

Returns

PDFForm

removeField()

removeField(field): void;

Defined in: src/api/form/PDFForm.ts:821

Remove a field from this [[PDFForm]].

For example:

const form = pdfDoc.getForm();
const ageField = form.getFields().find(x => x.getName() === 'Age');
form.removeField(ageField);

Parameters

Parameter	Type
`field`	`PDFField`

Returns

void

setXFAJavaScript()

setXFAJavaScript(
   fieldName, 
   eventName, 
   newScript): void;

Defined in: src/api/form/PDFForm.ts:496

Modify JavaScript in this form's XFA template for a specific field and event. For example:

const form = pdfDoc.getForm()
form.setXFAJavaScript('import', 'event__click', 'console.println("Modified!");')

Parameters

Parameter	Type	Description
`fieldName`	`string`	The name of the field containing the script
`eventName`	`string`	The name of the event (e.g., 'event__click', 'calculate')
`newScript`	`string`	The new JavaScript code to set

Returns

void

Throws

Error if the XFA form is not found, the script location is not found, or decoding fails

Note: load the document with preserveXFA: true. Prefer calling via [[PDFDocument.setXFAJavaScript]] before [[PDFDocument.getForm]] when preserveXFA is not set, since getForm() strips XFA data otherwise.

updateFieldAppearances()

updateFieldAppearances(font?): void;

Defined in: src/api/form/PDFForm.ts:883

Update the appearance streams for all widgets of all fields in this [[PDFForm]]. Appearance streams will only be created for a widget if it does not have any existing appearance streams, or the field's value has changed (e.g. by calling [[PDFTextField.setText]] or [[PDFDropdown.select]]).

For example:

const courier = await pdfDoc.embedFont(StandardFonts.Courier)
const form = pdfDoc.getForm()
form.updateFieldAppearances(courier)

IMPORTANT: The default value for the font parameter is [[StandardFonts.Helvetica]]. Note that this is a WinAnsi font. This means that encoding errors will be thrown if any fields contain text with characters outside the WinAnsi character set (the latin alphabet).

Embedding a custom font and passing that as the font parameter allows you to generate appearance streams with non WinAnsi characters (assuming your custom font supports them).

> NOTE: The [[PDFDocument.save]] method will call this method to > update appearances automatically if a form was accessed via the > [[PDFDocument.getForm]] method prior to saving.

Parameters

Parameter	Type	Description
`font?`	`PDFFont`	Optionally, the font to use when creating new appearances.

Returns

void

Class: PDFForm ​

Properties ​

acroForm ​

doc ​

Methods ​

createButton() ​

Parameters ​

Returns ​

createCheckBox() ​

Parameters ​

Returns ​

createDropdown() ​

Parameters ​

Returns ​

createOptionList() ​

Parameters ​

Returns ​

createRadioGroup() ​

Parameters ​

Returns ​

createTextField() ​

Parameters ​

Returns ​

deleteXFA() ​

Returns ​

fieldIsDirty() ​

Parameters ​

Returns ​

flatten() ​

Parameters ​

Returns ​

getButton() ​

Parameters ​

Returns ​

getCheckBox() ​

Parameters ​

Returns ​

getDefaultFont() ​

Returns ​

getDropdown() ​

Parameters ​

Returns ​

getField() ​

Parameters ​

Returns ​

getFieldMaybe() ​

Parameters ​

Returns ​

getFields() ​

Returns ​

getOptionList() ​

Parameters ​

Returns ​

getRadioGroup() ​

Parameters ​

Returns ​

getSignature() ​

Parameters ​

Returns ​

getSignatureFields() ​

Returns ​

getTextField() ​

Parameters ​

Returns ​

getXFAJavaScripts() ​

Returns ​

getXFASignatures() ​

Returns ​

hasXFA() ​

Returns ​

markFieldAsClean() ​

Parameters ​

Returns ​

markFieldAsDirty() ​

Parameters ​

Returns ​

of() ​

Parameters ​

Returns ​

removeField() ​

Class: PDFForm

Properties

acroForm

doc

Methods

createButton()

Parameters

Returns

createCheckBox()

Parameters

Returns

createDropdown()

Parameters

Returns

createOptionList()

Parameters

Returns

createRadioGroup()

Parameters

Returns

createTextField()

Parameters

Returns

deleteXFA()

Returns

fieldIsDirty()

Parameters

Returns

flatten()

Parameters

Returns

getButton()

Parameters

Returns

getCheckBox()

Parameters

Returns

getDefaultFont()

Returns

getDropdown()

Parameters

Returns

getField()

Parameters

Returns

getFieldMaybe()

Parameters

Returns

getFields()

Returns

getOptionList()

Parameters

Returns

getRadioGroup()

Parameters

Returns

getSignature()

Parameters

Returns

getSignatureFields()

Returns

getTextField()

Parameters

Returns

getXFAJavaScripts()

Returns

getXFASignatures()

Returns

hasXFA()

Returns

markFieldAsClean()

Parameters

Returns

markFieldAsDirty()

Parameters

Returns

of()

Parameters

Returns

removeField()