Section:

Create new PDF form fields using JavaScript

Form fields, also known as AcroForms, are a collection of fields such as text boxes, checkboxes, radio buttons, drop-down lists, push buttons, and more that will gather information interactively from the user.

One of the most important ideas to understand is the appearance (how it is displayed) of a form field is independent of the field itself and exists as a widget annotation. In fact, there can be multiple widget annotations for a single field. This gives the freedom to present a field appearance over multiple pages or even multiple times on the same page of a document.

Annotations and fields should be added to the document only after the document has finished loading. This can be done by listening for the DocumentViewer.documentLoaded event:

1WebViewer(...)
2  .then(instance => {
3    const { documentViewer } = instance.Core;
4    documentViewer.addEventListener('documentLoaded', () => {
5      // create field and widget annotations here
6    });
7  });

Related Links

Creating text fields

Text fields and widget annotations can be added programmatically. There are several properties and widget flags as highlighted below:

Text widget flags

Widget Flag

Description

Unique to text?

READ_ONLY

The field value cannot be changed.

No

REQUIRED

The field must have a value when exported.

No

MULTILINE

The field may contain multiple lines of text.

Yes

COMB

The field shall be automatically divided into as many equally spaced positions as the value of the max length.

Yes

DO_NOT_SCROLL

The field shall not scroll (horizontally for single-line fields, vertically for multiple-line fields) to accommodate more text than fits within its annotation rectangle.

Yes

DO_NOT_SPELL_CHECK

The field text shall not be spell-checked.

Yes

Text widget sample code

1WebViewer(...)
2.then(instance => {
3  const { annotationManager, Annotations, documentViewer } = instance.Core;
4  const { WidgetFlags } = Annotations;
5
6  documentViewer.addEventListener('documentLoaded', () => {
7    // Sets flags for the text widget.
8    const flags = new WidgetFlags();
9    flags.set(WidgetFlags.REQUIRED, true);
10    flags.set(WidgetFlags.MULTILINE, true);
11
12    // Creates a text form field.
13    const field = new Annotations.Forms.Field('TextFormField 1', {
14      type: 'Tx',
15      defaultValue: 'Default Value',
16      flags,
17    });
18
19    // Creates a text widget annotation.
20    const widgetAnnot = new Annotations.TextWidgetAnnotation(field);
21    widgetAnnot.PageNumber = 1;
22    widgetAnnot.X = 100;
23    widgetAnnot.Y = 100;
24    widgetAnnot.Width = 200;
25    widgetAnnot.Height = 50;
26
27    // Add form field to field manager and widget annotation to annotation manager.
28    annotationManager.getFieldManager().addField(field);
29    annotationManager.addAnnotation(widgetAnnot);
30    annotationManager.drawAnnotationsFromList([widgetAnnot]);
31  });
32});

Related Links

Creating signature fields

Signature fields and widget annotations can be added programmatically. There are several properties and widget flags as highlighted below:

Signature widget flags

Widget flag

Description

Unique to signature?

READ_ONLY

The field value cannot be changed.

No

REQUIRED

The field must have a value when exported.

No

Signature sample code

1WebViewer(...)
2.then(instance => {
3  const { annotationManager, Annotations, documentViewer } = instance.Core;
4  const { WidgetFlags } = Annotations;
5
6  documentViewer.addEventListener('documentLoaded', () => {
7    // Sets flags for the signature widget.
8    const flags = new WidgetFlags();
9    flags.set(WidgetFlags.REQUIRED, true);
10
11    // Creates a signature form field.
12    const field = new Annotations.Forms.Field('SignatureFormField 1', { 
13      type: 'Sig', 
14      flags,
15    });
16
17    // Creates a signature widget annotation.
18    const widgetAnnot = new Annotations.SignatureWidgetAnnotation(field, {
19      appearance: '_DEFAULT',
20      appearances: {
21        _DEFAULT: {
22          Normal: {
23            // Optionally can pass image data to appearance.
24            // data: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAAYdEVYdFNvZnR3YXJlAHBhaW50Lm5ldCA0LjEuMWMqnEsAAAANSURBVBhXY/j//z8DAAj8Av6IXwbgAAAAAElFTkSuQmCC',
25            offset: {
26              x: 100,
27              y: 100,
28            },
29          },
30        },
31      },
32    });
33
34    widgetAnnot.PageNumber = 1;
35    widgetAnnot.X = 100;
36    widgetAnnot.Y = 100;
37    widgetAnnot.Width = 100;
38    widgetAnnot.Height = 50;
39
40    // Add form field to field manager and widget annotation to annotation manager.
41    annotationManager.getFieldManager().addField(field);
42    annotationManager.addAnnotation(widgetAnnot);
43    annotationManager.drawAnnotationsFromList([widgetAnnot]);
44  });
45});

Related Links

Creating checkbox fields

Checkbox fields and widget annotations can be added programmatically. There are several properties and widget flags as highlighted below:

Checkbox caption options

Caption

Value

Result

Check

''

Apryse Docs Image

Circle

l

Apryse Docs Image

Cross

8

Apryse Docs Image

Diamond

u

Apryse Docs Image

Square

n

Apryse Docs Image

Star

H

Apryse Docs Image

Checkbox widget flags

Widget flag

Description

Unique to checkbox?

READ_ONLY

The field value cannot be changed.

No

REQUIRED

The field must have a value when exported.

No

Checkbox sample code

1WebViewer(...)
2.then(instance => {
3  const { annotationManager, Annotations, documentViewer } = instance.Core;
4  const { WidgetFlags } = Annotations;
5
6  documentViewer.addEventListener('documentLoaded', () => {
7    // Sets flags for the checkbox widget.
8    const flags = new WidgetFlags();
9    flags.set(WidgetFlags.REQUIRED, true);
10
11    // Creates a checkbox form field.
12    const field = new Annotations.Forms.Field('CheckboxField 1', {
13      type: 'Btn',
14      value: 'Off',
15      flags,
16    });
17
18    // Creates a checkbox widget annotation.
19    const widgetAnnot = new Annotations.CheckButtonWidgetAnnotation(field, {
20      appearance: 'Off',
21      appearances: {
22        Off: {},
23        Yes: {},
24      },
25      captions: {
26        Normal: '' // Uses the check symbol for selected caption.
27      }
28    });
29
30    widgetAnnot.PageNumber = 1;
31    widgetAnnot.X = 100;
32    widgetAnnot.Y = 100;
33    widgetAnnot.Width = 25;
34    widgetAnnot.Height = 25;
35
36    // Add form field to field manager and widget annotation to annotation manager.
37    annotationManager.getFieldManager().addField(field);
38    annotationManager.addAnnotation(widgetAnnot);
39    annotationManager.drawAnnotationsFromList([widgetAnnot]);
40  });
41});

Related Links

Creating combobox fields

Combobox (choice) fields and widget annotations can be added programmatically. There are several properties and widget flags as highlighted below:

Combobox widget flags

Widget flag

Description

Unique to combobox?

READ_ONLY

The field value cannot be changed.

No

REQUIRED

The field must have a value when exported.

No

COMBO

The field is a combobox. Must be true.

No

MULTI_SELECT

The field can have multiple selected values.

No

EDIT

If true, the combobox will include an editable text box with a dropdown.

Yes

Combobox sample code

1WebViewer(...)
2.then(instance => {
3  const { annotationManager, Annotations, documentViewer } = instance.Core;
4  const { WidgetFlags } = Annotations;
5
6  documentViewer.addEventListener('documentLoaded', () => {
7    // Sets flags for the combobox widget.
8    const flags = new WidgetFlags();
9    flags.set(WidgetFlags.COMBO, true);
10    flags.set(WidgetFlags.REQUIRED, true);
11
12    // Define the available options.
13    const comboOptions = [
14      { value: '1', displayValue: 'one' },
15      { value: '2', displayValue: 'two' },
16      { value: '3', displayValue: 'three' }
17    ];
18
19    // Specify a font-family and font size.
20    const font = new Annotations.Font({ name: 'Helvetica', size: 12 });
21
22    // Creates a combobox form field.
23    const field = new Annotations.Forms.Field('ComboBoxField 1', {
24      flags,
25      font,
26      type: 'Ch',
27      options: comboOptions,
28      value: comboOptions[0].value,
29    });
30
31    // Creates a combobox widget annotation.
32    const widgetAnnot = new Annotations.ChoiceWidgetAnnotation(field);
33    widgetAnnot.PageNumber = 1;
34    widgetAnnot.X = 100;
35    widgetAnnot.Y = 100;
36    widgetAnnot.Width = 200;
37    widgetAnnot.Height = 25;
38
39    // Add form field to field manager and widget annotation to annotation manager.
40    annotationManager.getFieldManager().addField(field);
41    annotationManager.addAnnotation(widgetAnnot);
42    annotationManager.drawAnnotationsFromList([widgetAnnot]);
43  });
44});

Related Links

Creating listbox fields

Listbox fields and widget annotations can be added programmatically. There are several properties and widget flags as highlighted below:

Listbox widget flags

Widget flag

Description

Unique to listbox?

READ_ONLY

The field value cannot be changed.

No

REQUIRED

The field must have a value when exported.

No

COMBO

The field is a listbox. Must be false.

No

MULTI_SELECT

The field can have multiple selected values.

No

Listbox sample code

1WebViewer(...)
2.then(instance => {
3  const { annotationManager, Annotations, documentViewer } = instance.Core;
4  const { WidgetFlags } = Annotations;
5
6  documentViewer.addEventListener('documentLoaded', () => {
7    // Sets flags for the listbox widget.
8    const flags = new WidgetFlags();
9    flags.set(WidgetFlags.COMBO, false);
10    flags.set(WidgetFlags.MULTI_SELECT, true);
11    flags.set(WidgetFlags.REQUIRED, true);
12
13    // Define the available options.
14    const listOptions = [
15      { value: '1', displayValue: 'one' },
16      { value: '2', displayValue: 'two' },
17      { value: '3', displayValue: 'three' }
18    ];
19
20    // Specify a font-family and font size.
21    const font = new Annotations.Font({ name: 'Helvetica', size: 12 });
22
23    // Creates a listbox form field.
24    const field = new Annotations.Forms.Field('ListBoxField 1', {
25      flags,
26      font,
27      type: 'Ch',
28      options: listOptions,
29      value: listOptions[0].value,
30    });
31
32    // Creates a listbox widget annotation.
33    const widgetAnnot = new Annotations.ListWidgetAnnotation(field);
34    widgetAnnot.PageNumber = 1;
35    widgetAnnot.X = 100;
36    widgetAnnot.Y = 100;
37    widgetAnnot.Width = 200;
38    widgetAnnot.Height = 50;
39
40    // Add form field to field manager and widget annotation to annotation manager.
41    annotationManager.getFieldManager().addField(field);
42    annotationManager.addAnnotation(widgetAnnot);
43    annotationManager.drawAnnotationsFromList([widgetAnnot]);
44  });
45});

Related Links

Creating radio button fields

Radio button fields and widget annotations can be added programmatically. There are several properties and widget flags as highlighted below:

Radio button widget flags

Widget flag

Description

Unique to radio?

READ_ONLY

The field value cannot be changed.

No

REQUIRED

The field must have a value when exported.

No

RADIO

This must be true otherwise it is a checkbox.

No

NO_TOGGLE_TO_OFF

If true only one radio button can be selected.

Yes

Radio button sample code

1WebViewer(...)
2.then(instance => {
3  const { annotationManager, Annotations, documentViewer } = instance.Core;
4  const { WidgetFlags } = Annotations;
5
6  documentViewer.addEventListener('documentLoaded', () => {
7    // Sets flags for the combobox widget.
8    const flags = new WidgetFlags();
9    flags.set(WidgetFlags.RADIO, true);
10    flags.set(WidgetFlags.NO_TOGGLE_TO_OFF, true);
11    flags.set(WidgetFlags.REQUIRED, true);
12
13    // Creates a radio button group form field.
14    const field = new Annotations.Forms.Field('RadioButtonGroupName 1', {
15      type: 'Btn',
16      value: 'Off',
17      flags
18    });
19
20    // Create a radio widget button.
21    const radioButton1 = new Annotations.RadioButtonWidgetAnnotation(field, {
22      appearance: 'Off',
23      appearances: {
24        Off: {},
25        First: {},
26      },
27    });
28
29    // Create another radio button widget.
30    const radioButton2 = new Annotations.RadioButtonWidgetAnnotation(field, {
31      appearance: 'Off',
32      appearances: {
33        Off: {},
34        Second: {},
35      },
36    });
37
38    radioButton1.PageNumber = 1;
39    radioButton1.X = 100;
40    radioButton1.Y = 100;
41    radioButton1.Width = 25;
42    radioButton1.Height = 25;
43
44    radioButton2.PageNumber = 1;
45    radioButton2.X = 150;
46    radioButton2.Y = 150;
47    radioButton2.Width = 25;
48    radioButton2.Height = 25;
49
50    // Add form field to field manager and widget annotation to annotation manager.
51    annotationManager.getFieldManager().addField(field);
52    annotationManager.addAnnotation(radioButton1);
53    annotationManager.addAnnotation(radioButton2);
54    annotationManager.drawAnnotationsFromList([radioButton1, radioButton2]);
55  });
56});

Related Links

Creating date picker fields

For form fields that expect a date to be input, WebViewer provides an interactive date picker widget to select a date from a calendar. Users can still type the date, but the date field can also be populated by using the calendar.

The calendar will automatically set the correct date format for the field so the user doesn't need to worry about entering the date in a specific format.

Apryse Docs Image

Date picker fields and widget annotations can be added programmatically. There are several properties and widget flags as highlighted below:

Date picker widget flags

Widget flag

Description

Unique to date picker?

READ_ONLY

The field value cannot be changed.

No

REQUIRED

The field must have a value when exported.

No

Date picker sample code

1WebViewer(...)
2.then(instance => {
3  const { annotationManager, Annotations, documentViewer } = instance.Core;
4  const { WidgetFlags } = Annotations;
5
6  documentViewer.addEventListener('documentLoaded', () => {
7    // Sets flags for the date picker widget.
8    const flags = new WidgetFlags();
9    flags.set(WidgetFlags.REQUIRED, true);
10
11    // Specify a font-family and font size.
12    const font = new Annotations.Font({ name: 'Helvetica', size: 12 });
13
14    // Creates a date picker form field.
15    const field = new Annotations.Forms.Field('DatePickerField 1', {
16      flags,
17      font,
18      type: 'Tx', // Date pickers are considered 'text' fields.
19    });
20
21    // Creates a date picker widget annotation.
22    const widgetAnnot = new Annotations.DatePickerWidgetAnnotation(field);
23    widgetAnnot.PageNumber = 1;
24    widgetAnnot.X = 25;
25    widgetAnnot.Y = 25;
26    widgetAnnot.Width = 100;
27    widgetAnnot.Height = 25;
28
29    // Add form field to field manager and widget annotation to annotation manager.
30    annotationManager.getFieldManager().addField(field);
31    annotationManager.addAnnotation(widgetAnnot);
32    annotationManager.drawAnnotationsFromList([widgetAnnot]);
33  });
34});

Related Links

Filling date field programmatically

Just like other PDF form fields, the date field can also be filled programmatically using the fieldManager or using the Annotations.DatePickerWidgetAnnotation instance.

Here is an example of filling date field programmatically:

JavaScript (v8.0+)

1WebViewer(...)
2  .then(instance => {
3    const { annotationManager, documentViewer } = instance.Core;
4    documentViewer.addEventListener('annotationsLoaded', () => {
5      // replace with id of date field in your document
6      const dateFieldId = 'DatePicker_1';
7      const field = annotationManager.getFieldManager().getField(dateFieldId);
8      field.setValue('6/15/20');
9      const widget = field.widgets[0];
10      widget.getDatePicker().show(); // open date picker widget
11      widget.getDatePicker().setDate('6/17/20');
12      field.setValue('6/7/20');
13      widget.refreshDatePicker(); // refresh widget
14    });
15    // ...
16});

Related Links

Date picker internationalization

The default i18n configuration format looks like this:

JavaScript (v8.0+)

1WebViewer(...)
2  .then(instance => {
3    const { Annotations } = instance.Core;
4    const { DatePickerWidgetAnnotation } = Annotations;
5    DatePickerWidgetAnnotation.datePickerOptions.i18n = {
6      previousMonth : 'Previous Month',
7      nextMonth     : 'Next Month',
8      months        : ['January','February','March','April','May','June','July',
9        'August','September','October','November','December'],
10      weekdays      : ['Sunday','Monday','Tuesday','Wednesday','Thursday','Friday',
11        'Saturday'],
12      weekdaysShort : ['Sun','Mon','Tue','Wed','Thu','Fri','Sat']
13    }
14    DatePickerWidgetAnnotation.datePickerOptions.firstDay = 0;
15    DatePickerWidgetAnnotation.datePickerOptions.isRTL = false;
16   // ...
17});

You must provide 12 months and 7 weekdays (with abbreviations). Always specify weekdays in this order with Sunday first. You can change the firstDay option to reorder if necessary (0: Sunday, 1: Monday, etc). You can also set isRTL to true for languages that are read from right-to-left.

Did you find this helpful?

Trial setup questions?

Ask experts on Discord

Need other help?

Contact Support

Pricing or product questions?

Contact Sales