Product:

Get started

Migration Guides

What is WebViewer

DocumentViewer

Open/Save Document

Events

UI customization

Annotation

Collaboration

MS Office

DOCX Editor

Spreadsheet Editor

Conversion

PDF/A

Forms

Overview

Fields and widgets

Form builder

Create form fields

Overview

Text Fields

Signature Fields

Checkbox Fields

Combobox Fields

Listbox Fields

Radio Button Fields

Date Picker Fields

Fill form fields

Style form fields

Modify form fields

Remove form fields

Form flatten

Import/export

Embedded JavaScript

APIs

Samples

Generate

Page manipulation

Edit page content

Extraction

Digital signature

Outlines/Bookmarks

Compare files

Optimization

Layers (OCGs)

Measurement

Redaction

Security

HTML

BIM

Video

Audio

Portfolios

Low-level PDF API

Full API

WebViewer Server

Custom server

Best practices

Advanced

Changelogs

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  });

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

Types of Fields to Add

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

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

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});

1WebViewer(...)
2  .then(instance => {
3    const { docViewer, annotManager, Annotations } = instance;
4
5    docViewer.on('documentLoaded', () => {
6      // create field and widget annotations here
7    });
8  });

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

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});

1WebViewer(...)
2  .then(instance => {
3    const { docViewer, annotManager, Annotations } = instance;
4
5    docViewer.on('documentLoaded', () => {
6      // create field and widget annotations here
7    });
8  });

Starting in WebViewer 8.9, you can create a Signature Widget that accepts initials. If a signature widget is flagged as requiresInitials, it will apply the initials created by the user in the signature modal. This optional parameter can be passed when instantiating a Signature Widget. Please note that the initials feature must be enabled in order for this to be displayed in the viewer. For a sample on how to do this refer to this guide.

JavaScript

1WebViewer(...)
2.then(instance => {
3  const { annotationManager, Annotations } = instance.Core;
4  const { WidgetFlags } = Annotations;
5
6  // myBtn is your own custom button
7  document.getElementById('myBtn').addEventListener('click', () => {
8
9    // set flags for required
10    const flags = new WidgetFlags();
11    flags.set('Required', true);
12
13    // create a form field
14    const field = new Annotations.Forms.Field("some signature field name", { 
15      type: 'Sig', 
16      flags,
17    });
18
19    // create a widget annotation
20    const widgetAnnot = new Annotations.SignatureWidgetAnnotation(field, {
21      appearance: '_DEFAULT',
22      appearances: {
23        _DEFAULT: {
24          Normal: {
25            offset: {
26              x: 100,
27              y: 100,
28            },
29          },
30        },
31      },
32      // If this option is passed, the widget will apply any 
33      // initials created by the user in the Signature Modal
34      requiresInitials: true,
35    });
36    
37    // to show the 'initials' field indicator on widget import
38    widgetAnnot.setCustomData('trn-signature-type', 'initialsSignature')
39
40    // set position and size
41    widgetAnnot.PageNumber = 1;
42    widgetAnnot.X = 100;
43    widgetAnnot.Y = 100;
44    widgetAnnot.Width = 50;
45    widgetAnnot.Height = 20;
46
47    //add the form field and widget annotation
48    annotationManager.getFieldManager().addField(field);
49    annotationManager.addAnnotation(widgetAnnot);
50    annotationManager.drawAnnotationsFromList([widgetAnnot]);
51  });
52});

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	`''`
Circle	`l`
Cross	`8`
Diamond	`u`
Square	`n`
Star	`H`

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});

1WebViewer(...)
2  .then(instance => {
3    const { docViewer, annotManager, Annotations } = instance;
4
5    docViewer.on('documentLoaded', () => {
6      // create field and widget annotations here
7    });
8  });

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

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});

1WebViewer(...)
2  .then(instance => {
3    const { docViewer, annotManager, Annotations } = instance;
4
5    docViewer.on('documentLoaded', () => {
6      // create field and widget annotations here
7    });
8  });

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

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});

1WebViewer(...)
2  .then(instance => {
3    const { docViewer, annotManager, Annotations } = instance;
4
5    docViewer.on('documentLoaded', () => {
6      // create field and widget annotations here
7    });
8  });

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

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});

1WebViewer(...)
2  .then(instance => {
3    const { docViewer, annotManager, Annotations } = instance;
4
5    docViewer.on('documentLoaded', () => {
6      // create field and widget annotations here
7    });
8  });

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.

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

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});

1WebViewer(...)
2  .then(instance => {
3    const { docViewer, annotManager, Annotations } = instance;
4
5    docViewer.on('documentLoaded', () => {
6      // create field and widget annotations here
7    });
8  });

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 (SDK 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});

Date picker internationalization

The default i18n configuration format looks like this:

JavaScript (SDK 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

Product:

Product:

Create new PDF form fields using JavaScript

Widget Annotation

Types of Fields to Add

Text widget flags

Text widget sample code

Signature widget flags

Signature sample code

Creating a signature widget to accept initials

JavaScript

Checkbox caption options

Checkbox widget flags

Checkbox sample code

Combobox widget flags

Combobox sample code

Listbox widget flags

Listbox sample code

Radio button widget flags

Radio button sample code

Date picker widget flags

Date picker sample code

Filling date field programmatically

JavaScript (SDK v8.0+)

Date picker internationalization

JavaScript (SDK v8.0+)

On this page

Product:

Product:

Create new PDF form fields using JavaScript

Widget Annotation

Related Links

Related Links

Types of Fields to Add

Text widget flags

Text widget sample code

Related Links

Related Links

Signature widget flags

Signature sample code

Related Links

Related Links

Creating a signature widget to accept initials

JavaScript

Related Links

Checkbox caption options

Checkbox widget flags

Checkbox sample code

Related Links

Related Links

Combobox widget flags

Combobox sample code

Related Links

Related Links

Listbox widget flags

Listbox sample code

Related Links

Related Links

Radio button widget flags

Radio button sample code

Related Links

Related Links

Date picker widget flags

Date picker sample code

Related Links

Related Links

Filling date field programmatically

JavaScript (SDK v8.0+)

Related Links

Date picker internationalization

JavaScript (SDK v8.0+)

On this page