Introduction to Forms

Form Support of PSPDFKit

PSPDFKit supports most form types defined by the PDF specification. We have to differentiate between field objects and annotation objects.

Type Field Object Annotation Object
Check box CheckBoxFormField WidgetAnnotation
Radio button RadioButtonFormField WidgetAnnotation
Push buttons ButtonFormField WidgetAnnotation
List box ListBoxFormField WidgetAnnotation
Combo box ComboBoxFormField WidgetAnnotation
Text TextFormField WidgetAnnotation
Digital signatures Coming in a future release

Field objects have no visual representation of their own and are represented by FormField, while annotation objects are visual representations of a single control inside a form field and are represented by WidgetAnnotation.

In order to render a WidgetAnnotation, the associated FormField will be accessed via the WidgetAnnotation#formFieldName property. Based on the type of this FormField, different form controls are rendered.

We currently render generic elements for every form field type. Rendering the custom appearance stream for form fields is planned for a future release.

For now, FormField and WidgetAnnotation objects are read-only and cannot be modified. You can, however, modify the current values of form fields using a programmable form-filling API.

Retrieving Form Field and Annotation Objects

Retrieving all form field objects is easily done by using the Instance#getFormFields API. This API is asynchronous and will return a promise that resolves to an immutable list of FormField elements and contains their current values. Every FormField has a unique name property. In the PDF spec, this is often referred to as the fully qualified name. This name is similar to an input name in an HTML form and is used to associate the filled-out value with the form field:

1
2
const formFields = await instance.getFormFields();
console.log(formFields.size);
1
2
3
instance.getFormFields().then(function(formFields) {
  console.log(formFields.size);
});

WidgetAnnotations behave like regular annotations and can be loaded via the regular annotations API. Widgets are currently not exported by the annotation backend and are thus read-only.

Form Field Values

To make it as easy as possible to get the current form field values of a PDF, we added another API. Instance#getFormFieldValues returns a simple JavaScript object, where the keys refer to the FormField#name of the form field and the value is either null, string, or Array<string>, depending upon the type of the FormField:

Copy
1
2
const formFieldValues = instance.getFormFieldValues();
console.log(formFieldValues); // => { textField: 'Text Value', checkBoxField: ['A', 'B'], buttonField: null }
Copy
1
2
var formFieldValues = instance.getFormFieldValues();
console.log(formFieldValues); // => { textField: 'Text Value', checkBoxField: ['A', 'B'], buttonField: null }

JavaScript Support

PSPDFKit for Web currently has no support for executing JavaScript inside a document. This support is planned for a future release.