Introduction to Forms

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 Boxes CheckBoxFormField WidgetAnnotation
Radio Buttons RadioButtonFormField WidgetAnnotation
Push Buttons ButtonFormField WidgetAnnotation
List Boxes ListBoxFormField WidgetAnnotation
Combo Boxes 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.

We also allow creating a FormField and a WidgetAnnotation directly from a loaded instance, and this is described in the Form Creation guide. You can also modify the values of these form fields using the UI or 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.

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

In standalone mode, PSPDFKit for Web supports executing JavaScript from within a document, allowing for custom behaviors in response to user interactions with form fields. The most common JavaScript API methods and properties useful for working with forms are supported, however, JavaScript is a relatively new feature that we are constantly working on improving, so please be aware that you may receive unexpected results. See the dedicated JavaScript Support section for more information.