Fields and Widgets

Form fields and widget annotations are the two main components of a form workflow. Form fields represent the data entry points for users, while widget annotations serve as the visual elements that encapsulate these fields, providing interactive components like checkboxes, text boxes, and dropdown menus. The sections below cover some of the common use cases when working with form fields and widgets.

Creating form fields

Creating form fields requires you to define the value and type of the field, along with some optional parameters. You can find a detailed explanation on field creation by visiting Creating form fields. Below is a simple example of a text field.

JavaScript

WebViewer(...)
  .then(instance => {
    const { Annotations, annotationManager } = instance.Core;
    const field = new Annotations.Forms.Field('Field Name', { type: 'Tx' });
    annotationManager.getFieldManager().addField(field);
  });

Field FieldManager#addField

Setting widget flags

WidgetFlags allow you to define certain behaviors of a field and its associated widgets. The available flags may change over time, but these are the currently supported WidgetFlags. A WidgetFlags object can be passed to a form field at creation to define the default state of the field.

JavaScript

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

    const flags = new WidgetFlags();
    flags.set(WidgetFlags.MULTILINE, true);
    flags.set(WidgetFlags.REQUIRED, true);

    const field = new Annotations.Forms.Field('Field Name', {
      flags
      type: 'Tx'
    });

    annotationManager.getFieldManager().addField(field);
  });

Field WidgetFlags FieldManager#addField

Updating widget flags

You can update WidgetFlags by accessing the WidgetFlags that have been added to the field. This can be done by calling the set method. All WidgetFlags accept a boolean value to determine the desired state.

JavaScript

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

    // Create a field with READ_ONLY flag set to true.
    const flags = new WidgetFlags();
    flags.set(WidgetFlags.READ_ONLY, true);
    const field = new Annotations.Forms.Field('Field Name', {
      flags
      type: 'Tx',
    });

    // Modify the flag to set READ_ONLY to false.
    field.flags.set(WidgetFlags.READ_ONLY, false);
    annotationManager.getFieldManager().addField(field);
  });

Field WidgetFlags WidgetFlags#set FieldManager#addField

Updating field values

The most consistent way to update a field's value is to call the setValue method on the field object. This will result in the field being updated along with all of the associated widgets.

JavaScript

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

    const field = new Annotations.Forms.Field('Field Name', { type: 'Tx' });

    field.setValue("Hello World");
    annotationManager.getFieldManager().addField(field);
  });

Field#setValue FieldManager#addField

Highlighting Widgets

Form field highlighting is enabled by default to visually indicate interactive fields in the UI. This applies to:

• Text fields
• Choice fields
• Signature fields
• Checkboxes
• Radio buttons

However, highlight is not applied to push buttons. Highlighting is a UI-only visual cue and does not change the underlying widget styling or appearance.

Form Fields highlighted

You could choose to enable or disable the highlight with the following APIs:

JavaScript

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

    const annotationManager = instance.Core.documentViewer.getAnnotationManager();
    const fieldManager = annotationManager.getFieldManager();
  
    // Enable/disable standard widget highlighting
    fieldManager.enableWidgetHighlighting();
    fieldManager.disableWidgetHighlighting();
  });

FieldManager#enableWidgetHighlighting FieldManager#disableWidgetHighlighting

Configuring multiple widgets for a single field

The PDF specification allows multiple widgets to be associated with a single field, ensuring consistency across these widgets. For instance, a user may want to enter their first name only once and have it shown in multiple places in the form. We support this functionality by passing the same field into different widgets during object creation.

JavaScript

function createWidget (field, options, x, y, Annotations) {
  let newWidget = new Annotations.TextWidgetAnnotation(field, options);
  newWidget.PageNumber = 1;
  newWidget.X = x;
  newWidget.Y = y;
  newWidget.Width = 50;
  newWidget.Height = 20;
  return newWidget;
}

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

    const field = new Annotations.Forms.Field('Field Name', { type: 'Tx' });

    const widgetAnnot = createWidget(field, {}, 100, 100, Annotations);
    const widgetAnnot02 = createWidget(field, {}, 200, 200, Annotations);

    annotationManager.getFieldManager().addField(field);
    annotationManager.addAnnotations([widgetAnnot, widgetAnnot02]);
    annotationManager.drawAnnotationsFromList([widgetAnnot]);
  });

Field FieldManager#addField AnnotationManager#addAnnotations AnnotationManager#drawAnnotationsFromList AnnotationManager#getFieldManager

Configuring widgets across multiple pages

You can also link widget annotations across multiple pages to a single form field. The same update behavior mentioned in the previous section applies. In the example below, we extend the createWidget function to accept a Page argument. Finally, we attach multiple cross-page widgets to a single field. This allows you to have shared fields across multiple PDF pages, streamlining data entry and ensuring that updates to one widget are automatically propagated to the other widgets that relate to the same field.

JavaScript

function createWidget (field, options, x, y, Annotations, page = 1) {
  let newWidget = new Annotations.TextWidgetAnnotation(field, options);
  newWidget.PageNumber = page;
  newWidget.X = x;
  newWidget.Y = y;
  newWidget.Width = 50;
  newWidget.Height = 20;
  return newWidget;
}

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

    const field = new Annotations.Forms.Field('Field Name', { type: 'Tx' });

    const widgetAnnot01_page1 = createWidget(field, {}, 100, 100, Annotations);
    const widgetAnnot02_page1 = createWidget(field, {}, 200, 200, Annotations);
    const widgetAnnot03_page2 = createWidget(field, {}, 200, 200, Annotations, 2);
    const widgetAnnot04_page3 = createWidget(field, {}, 200, 200, Annotations, 3);

    const widgetsToAdd = [
      widgetAnnot01_page1,
      widgetAnnot02_page1,
      widgetAnnot03_page2,
      widgetAnnot04_page3
    ];

    annotationManager.getFieldManager().addField(field);
    annotationManager.addAnnotations(widgetsToAdd);
    annotationManager.drawAnnotationsFromList(widgetsToAdd);
  });

Field FieldManager#addField AnnotationManager#addAnnotations AnnotationManager#drawAnnotationsFromList AnnotationManager#getFieldManager

Additional field properties

The field has optional additional properties that can further define its behavior.

Max length

This defines the maximum number of characters that can be inputted into the field.

JavaScript

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

    const field = new Annotations.Forms.Field('Field Name', { type: 'Tx' });
    field.set({ maxLen: 5 });

    annotationManager.getFieldManager().addField(field);
  });

Field#set FieldManager#addField AnnotationManager#getFieldManager

Tooltips

This defines the tooltip that will be displayed when a user hovers over the widget annotation.

JavaScript

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

    const field = new Annotations.Forms.Field('Field Name', { type: 'Tx' });
    field.set({ tooltipName: `I'm a tooltip!` });

    annotationManager.getFieldManager().addField(field);
  });

Field#set FieldManager#addField AnnotationManager#getFieldManager

Options

Options are only applicable to list box and combo box field types. They define the possible values a user can select when interacting with these fields.

JavaScript

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

    const options = [
      { value: 'option1', displayValue: '1' },
      { value: 'option2', displayValue: '2' },
      { value: 'option3', displayValue: '3' },
      { value: 'option4', displayValue: '4' },
    ];

    // Creates a listbox field. WidgetFlags.COMBO is false by default, so no `flags` object is needed.
    field = new Annotations.Forms.Field('Field Name', {
      type: 'Ch',
      options
    });

    annotationManager.getFieldManager().addField(field);
  });

Field FieldManager#addField AnnotationManager#getFieldManager

Checkbox Widgets and Appearances

Checkbox widgets can also have appearances like Annotations. However, some files can have appearances that don’t match their values. If the value or appearance state is set to On, then the checkbox will be checked in WebViewer.

Checkbox Value	Appearance	Rendered State
On	On	On
Off	Off	Off
On	Off	On
Off	On	On