Some test text!

WebViewer SDK

Pricing

Downloads

FAQ

API

Samples

Changelog

Demo

Guides

Web / Guides / Create form fields

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:

WebViewer(...)
  .then(instance => {
    const { documentViewer } = instance.Core;
    documentViewer.addEventListener('documentLoaded', () => {
      // create field and widget annotations here
    });
  });

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

WebViewer(...)
.then(instance => {
  const { annotationManager, Annotations, documentViewer } = instance.Core;
  const { WidgetFlags } = Annotations;

  documentViewer.addEventListener('documentLoaded', () => {
    // Sets flags for the text widget.
    const flags = new WidgetFlags();
    flags.set(WidgetFlags.REQUIRED, true);
    flags.set(WidgetFlags.MULTILINE, true);

    // Creates a text form field.
    const field = new Annotations.Forms.Field('TextFormField 1', {
      type: 'Tx',
      defaultValue: 'Default Value',
      flags,
    });

    // Creates a text widget annotation.
    const widgetAnnot = new Annotations.TextWidgetAnnotation(field);
    widgetAnnot.PageNumber = 1;
    widgetAnnot.X = 100;
    widgetAnnot.Y = 100;
    widgetAnnot.Width = 200;
    widgetAnnot.Height = 50;

    // Add form field to field manager and widget annotation to annotation manager.
    annotationManager.getFieldManager().addField(field);
    annotationManager.addAnnotation(widgetAnnot);
    annotationManager.drawAnnotationsFromList([widgetAnnot]);
  });
});

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

WebViewer(...)
.then(instance => {
  const { annotationManager, Annotations, documentViewer } = instance.Core;
  const { WidgetFlags } = Annotations;

  documentViewer.addEventListener('documentLoaded', () => {
    // Sets flags for the signature widget.
    const flags = new WidgetFlags();
    flags.set(WidgetFlags.REQUIRED, true);

    // Creates a signature form field.
    const field = new Annotations.Forms.Field('SignatureFormField 1', { 
      type: 'Sig', 
      flags,
    });

    // Creates a signature widget annotation.
    const widgetAnnot = new Annotations.SignatureWidgetAnnotation(field, {
      appearance: '_DEFAULT',
      appearances: {
        _DEFAULT: {
          Normal: {
            // Optionally can pass image data to appearance.
            // data: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAAYdEVYdFNvZnR3YXJlAHBhaW50Lm5ldCA0LjEuMWMqnEsAAAANSURBVBhXY/j//z8DAAj8Av6IXwbgAAAAAElFTkSuQmCC',
            offset: {
              x: 100,
              y: 100,
            },
          },
        },
      },
    });

    widgetAnnot.PageNumber = 1;
    widgetAnnot.X = 100;
    widgetAnnot.Y = 100;
    widgetAnnot.Width = 100;
    widgetAnnot.Height = 50;

    // Add form field to field manager and widget annotation to annotation manager.
    annotationManager.getFieldManager().addField(field);
    annotationManager.addAnnotation(widgetAnnot);
    annotationManager.drawAnnotationsFromList([widgetAnnot]);
  });
});

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

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

WebViewer(...)
.then(instance => {
  const { annotationManager, Annotations, documentViewer } = instance.Core;
  const { WidgetFlags } = Annotations;

  documentViewer.addEventListener('documentLoaded', () => {
    // Sets flags for the checkbox widget.
    const flags = new WidgetFlags();
    flags.set(WidgetFlags.REQUIRED, true);

    // Creates a checkbox form field.
    const field = new Annotations.Forms.Field('CheckboxField 1', {
      type: 'Btn',
      value: 'Off',
      flags,
    });

    // Creates a checkbox widget annotation.
    const widgetAnnot = new Annotations.CheckButtonWidgetAnnotation(field, {
      appearance: 'Off',
      appearances: {
        Off: {},
        Yes: {},
      },
      captions: {
        Normal: '' // Uses the check symbol for selected caption.
      }
    });

    widgetAnnot.PageNumber = 1;
    widgetAnnot.X = 100;
    widgetAnnot.Y = 100;
    widgetAnnot.Width = 25;
    widgetAnnot.Height = 25;

    // Add form field to field manager and widget annotation to annotation manager.
    annotationManager.getFieldManager().addField(field);
    annotationManager.addAnnotation(widgetAnnot);
    annotationManager.drawAnnotationsFromList([widgetAnnot]);
  });
});

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

WebViewer(...)
.then(instance => {
  const { annotationManager, Annotations, documentViewer } = instance.Core;
  const { WidgetFlags } = Annotations;

  documentViewer.addEventListener('documentLoaded', () => {
    // Sets flags for the combobox widget.
    const flags = new WidgetFlags();
    flags.set(WidgetFlags.COMBO, true);
    flags.set(WidgetFlags.REQUIRED, true);

    // Define the available options.
    const comboOptions = [
      { value: '1', displayValue: 'one' },
      { value: '2', displayValue: 'two' },
      { value: '3', displayValue: 'three' }
    ];

    // Specify a font-family and font size.
    const font = new Annotations.Font({ name: 'Helvetica', size: 12 });

    // Creates a combobox form field.
    const field = new Annotations.Forms.Field('ComboBoxField 1', {
      flags,
      font,
      type: 'Ch',
      options: comboOptions,
      value: comboOptions[0].value,
    });

    // Creates a combobox widget annotation.
    const widgetAnnot = new Annotations.ChoiceWidgetAnnotation(field);
    widgetAnnot.PageNumber = 1;
    widgetAnnot.X = 100;
    widgetAnnot.Y = 100;
    widgetAnnot.Width = 200;
    widgetAnnot.Height = 25;

    // Add form field to field manager and widget annotation to annotation manager.
    annotationManager.getFieldManager().addField(field);
    annotationManager.addAnnotation(widgetAnnot);
    annotationManager.drawAnnotationsFromList([widgetAnnot]);
  });
});

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

WebViewer(...)
.then(instance => {
  const { annotationManager, Annotations, documentViewer } = instance.Core;
  const { WidgetFlags } = Annotations;

  documentViewer.addEventListener('documentLoaded', () => {
    // Sets flags for the listbox widget.
    const flags = new WidgetFlags();
    flags.set(WidgetFlags.COMBO, false);
    flags.set(WidgetFlags.MULTI_SELECT, true);
    flags.set(WidgetFlags.REQUIRED, true);

    // Define the available options.
    const listOptions = [
      { value: '1', displayValue: 'one' },
      { value: '2', displayValue: 'two' },
      { value: '3', displayValue: 'three' }
    ];

    // Specify a font-family and font size.
    const font = new Annotations.Font({ name: 'Helvetica', size: 12 });

    // Creates a listbox form field.
    const field = new Annotations.Forms.Field('ListBoxField 1', {
      flags,
      font,
      type: 'Ch',
      options: listOptions,
      value: listOptions[0].value,
    });

    // Creates a listbox widget annotation.
    const widgetAnnot = new Annotations.ListWidgetAnnotation(field);
    widgetAnnot.PageNumber = 1;
    widgetAnnot.X = 100;
    widgetAnnot.Y = 100;
    widgetAnnot.Width = 200;
    widgetAnnot.Height = 50;

    // Add form field to field manager and widget annotation to annotation manager.
    annotationManager.getFieldManager().addField(field);
    annotationManager.addAnnotation(widgetAnnot);
    annotationManager.drawAnnotationsFromList([widgetAnnot]);
  });
});

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

WebViewer(...)
.then(instance => {
  const { annotationManager, Annotations, documentViewer } = instance.Core;
  const { WidgetFlags } = Annotations;

  documentViewer.addEventListener('documentLoaded', () => {
    // Sets flags for the combobox widget.
    const flags = new WidgetFlags();
    flags.set(WidgetFlags.RADIO, true);
    flags.set(WidgetFlags.NO_TOGGLE_TO_OFF, true);
    flags.set(WidgetFlags.REQUIRED, true);

    // Creates a radio button group form field.
    const field = new Annotations.Forms.Field('RadioButtonGroupName 1', {
      type: 'Btn',
      value: 'Off',
      flags
    });

    // Create a radio widget button.
    const radioButton1 = new Annotations.RadioButtonWidgetAnnotation(field, {
      appearance: 'Off',
      appearances: {
        Off: {},
        First: {},
      },
    });

    // Create another radio button widget.
    const radioButton2 = new Annotations.RadioButtonWidgetAnnotation(field, {
      appearance: 'Off',
      appearances: {
        Off: {},
        Second: {},
      },
    });

    radioButton1.PageNumber = 1;
    radioButton1.X = 100;
    radioButton1.Y = 100;
    radioButton1.Width = 25;
    radioButton1.Height = 25;

    radioButton2.PageNumber = 1;
    radioButton2.X = 150;
    radioButton2.Y = 150;
    radioButton2.Width = 25;
    radioButton2.Height = 25;

    // Add form field to field manager and widget annotation to annotation manager.
    annotationManager.getFieldManager().addField(field);
    annotationManager.addAnnotation(radioButton1);
    annotationManager.addAnnotation(radioButton2);
    annotationManager.drawAnnotationsFromList([radioButton1, radioButton2]);
  });
});

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.

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

WebViewer(...)
.then(instance => {
  const { annotationManager, Annotations, documentViewer } = instance.Core;
  const { WidgetFlags } = Annotations;

  documentViewer.addEventListener('documentLoaded', () => {
    // Sets flags for the date picker widget.
    const flags = new WidgetFlags();
    flags.set(WidgetFlags.REQUIRED, true);

    // Specify a font-family and font size.
    const font = new Annotations.Font({ name: 'Helvetica', size: 12 });

    // Creates a date picker form field.
    const field = new Annotations.Forms.Field('DatePickerField 1', {
      flags,
      font,
      type: 'Tx', // Date pickers are considered 'text' fields.
    });

    // Creates a date picker widget annotation.
    const widgetAnnot = new Annotations.DatePickerWidgetAnnotation(field);
    widgetAnnot.PageNumber = 1;
    widgetAnnot.X = 25;
    widgetAnnot.Y = 25;
    widgetAnnot.Width = 100;
    widgetAnnot.Height = 25;

    // Add form field to field manager and widget annotation to annotation manager.
    annotationManager.getFieldManager().addField(field);
    annotationManager.addAnnotation(widgetAnnot);
    annotationManager.drawAnnotationsFromList([widgetAnnot]);
  });
});

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:

WebViewer(...)
  .then(instance => {
    const { annotationManager, documentViewer } = instance.Core;
    documentViewer.addEventListener('annotationsLoaded', () => {
      // replace with id of date field in your document
      const dateFieldId = 'DatePicker_1';
      const field = annotationManager.getFieldManager().getField(dateFieldId);
      field.setValue('6/15/20');

      const widget = field.widgets[0];
      widget.getDatePicker().show(); // open date picker widget
      widget.getDatePicker().setDate('6/17/20');

      field.setValue('6/7/20');
      widget.refreshDatePicker(); // refresh widget
    });
    // ...
});

Date picker internationalization

The default i18n configuration format looks like this:

WebViewer(...)
  .then(instance => {
    const { Annotations } = instance.Core;
    const { DatePickerWidgetAnnotation } = Annotations;

    DatePickerWidgetAnnotation.datePickerOptions.i18n = {
      previousMonth : 'Previous Month',
      nextMonth     : 'Next Month',
      months        : ['January','February','March','April','May','June','July',
        'August','September','October','November','December'],
      weekdays      : ['Sunday','Monday','Tuesday','Wednesday','Thursday','Friday',
        'Saturday'],
      weekdaysShort : ['Sun','Mon','Tue','Wed','Thu','Fri','Sat']
    }

    DatePickerWidgetAnnotation.datePickerOptions.firstDay = 0;
    DatePickerWidgetAnnotation.datePickerOptions.isRTL = false;
   // ...
});

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.

Trial setup questions? Ask experts on Discord
Need other help? Contact Support
Pricing or product questions? Contact Sales

Did you find this guide helpful?

Yes