PDFForm · PDF-LIB

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.

Hierarchy

PDFForm

Index

Properties

acroForm
doc

Methods

Properties

acroForm

• acroForm: PDFAcroForm

Defined in api/form/PDFForm.ts:76

The low-level PDFAcroForm wrapped by this form.

doc

• doc: PDFDocument

Defined in api/form/PDFForm.ts:79

The document to which this form belongs.

Methods

createButton

▸ createButton(name: string): PDFButton

Defined in api/form/PDFForm.ts:347

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:

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

Returns: PDFButton

The new button field.

createCheckBox

▸ createCheckBox(name: string): PDFCheckBox

Defined in api/form/PDFForm.ts:377

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:

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

Returns: PDFCheckBox

The new check box field.

createDropdown

▸ createDropdown(name: string): PDFDropdown

Defined in api/form/PDFForm.ts:407

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:

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

Returns: PDFDropdown

The new dropdown field.

createOptionList

▸ createOptionList(name: string): PDFOptionList

Defined in api/form/PDFForm.ts:437

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:

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

Returns: PDFOptionList

The new option list field.

createRadioGroup

▸ createRadioGroup(name: string): PDFRadioGroup

Defined in api/form/PDFForm.ts:468

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:

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

Returns: PDFRadioGroup

The new radio group field.

createTextField

▸ createTextField(name: string): PDFTextField

Defined in api/form/PDFForm.ts:502

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:

Name	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 api/form/PDFForm.ts:124

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: PDFRef): boolean

Defined in api/form/PDFForm.ts:694

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:

Name	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: FlattenOptions): void

Defined in api/form/PDFForm.ts:537

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:

Name	Type	Default
`options`	FlattenOptions	{ updateFieldAppearances: true }

Returns: void

getButton

▸ getButton(name: string): PDFButton

Defined in api/form/PDFForm.ts:202

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:

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

Returns: PDFButton

The button with the specified name.

getCheckBox

▸ getCheckBox(name: string): PDFCheckBox

Defined in api/form/PDFForm.ts:222

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:

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

Returns: PDFCheckBox

The check box with the specified name.

getDefaultFont

▸ getDefaultFont(): PDFFont‹›

Defined in api/form/PDFForm.ts:699

Returns: PDFFont‹›

getDropdown

▸ getDropdown(name: string): PDFDropdown

Defined in api/form/PDFForm.ts:243

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:

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

Returns: PDFDropdown

The dropdown with the specified name.

getField

▸ getField(name: string): PDFField

Defined in api/form/PDFForm.ts:184

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:

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

Returns: PDFField

The field with the specified name.

getFieldMaybe

▸ getFieldMaybe(name: string): PDFField | undefined

Defined in api/form/PDFForm.ts:164

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:

Name	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 api/form/PDFForm.ts:141

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: string): PDFOptionList

Defined in api/form/PDFForm.ts:264

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:

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

Returns: PDFOptionList

The option list with the specified name.

getRadioGroup

▸ getRadioGroup(name: string): PDFRadioGroup

Defined in api/form/PDFForm.ts:285

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:

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

Returns: PDFRadioGroup

The radio group with the specified name.

getSignature

▸ getSignature(name: string): PDFSignature

Defined in api/form/PDFForm.ts:304

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:

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

Returns: PDFSignature

The signature with the specified name.

getTextField

▸ getTextField(name: string): PDFTextField

Defined in api/form/PDFForm.ts:324

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:

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

Returns: PDFTextField

The text field with the specified name.

hasXFA

▸ hasXFA(): boolean

Defined in api/form/PDFForm.ts:109

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: PDFRef): void

Defined in api/form/PDFForm.ts:679

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:

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

Returns: void

markFieldAsDirty

▸ markFieldAsDirty(fieldRef: PDFRef): void

Defined in api/form/PDFForm.ts:664

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:

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

Returns: void

removeField

▸ removeField(field: PDFField): void

Defined in api/form/PDFForm.ts:583

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:

Name	Type
`field`	PDFField

Returns: void

updateFieldAppearances

▸ updateFieldAppearances(font?: PDFFont): void

Defined in api/form/PDFForm.ts:639

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:

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

Returns: void

`Static` of

▸ of(acroForm: PDFAcroForm, doc: PDFDocument): PDFForm‹›

Defined in api/form/PDFForm.ts:72

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:

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

Returns: PDFForm‹›

Hierarchy

Index

Properties

Methods

Properties

acroForm

doc

Methods

createButton

createCheckBox

createDropdown

createOptionList

createRadioGroup

createTextField

deleteXFA

fieldIsDirty

flatten

getButton

getCheckBox

getDefaultFont

getDropdown

getField

getFieldMaybe

getFields

getOptionList

getRadioGroup

getSignature

getTextField

hasXFA

markFieldAsClean

markFieldAsDirty

removeField

updateFieldAppearances

Static of

`Static` of