Format and Validate PDF Form Field Values

• Jul 13, 2026
• 3 minutes to read

Note

Value formatting is available only for text box and combo box form fields. Other form field types do not support value formatting.

The PDF Document API allows you to control how users enter and view values in text box and combo box form fields. You can apply built-in formatting rules or specify JavaScript to validate or format user input.

Built-in formatting

Suitable for common data types, such as dates, numbers, percentages, and times.

JavaScript formatting

Allows you to implement custom validation and formatting logic in PDF viewers that support JavaScript.

Apply a Built-in Value Format

Use the setValueFormat() method to assign a predefined format to a TextBoxField or ComboBoxField.

Call one of the FormFieldValueFormat static methods to create a format.

The following code snippet configures a text field to accept dates in the MMMM/dd/yyyy format:

// Create a text field.
TextBoxField dateField = new TextBoxField("Date");

// Apply a date format.
dateField.setValueFormat(FormFieldValueFormat.createDateTimeFormat("MMMM/dd/yyyy"));

pdfDocument.getFields().add(dateField);

Available Built-in Formats

The FormFieldValueFormat class introduces the following methods to create formats:

Method	Description
createDateTimeFormat()	Formats date and time values.
createNumberFormat()	Formats numeric values.
createPercentFormat()	Formats percentages.
createSpecialFormat()	Formats values using predefined patterns (for example, ZIP codes or phone numbers).
createTimeFormat()	Formats time values.

Use JavaScript to Format Input

Assign JavaScript to the FormFieldValueFormat object to specify how a field validates, formats, or recalculates its value.

The following code snippet formats the entered value and inserts hyphens between characters:

TextBoxField textField = new TextBoxField("Code");
FormFieldValueFormat format = new FormFieldValueFormat();

format.setFormatScript(
    "if (event.value != '') {" +
    "var value = event.value;" +
    "event.value = '';" +
    "for (var i = 0; i < value.length - 1; i++)" +
    "    event.value += value.charAt(i) + '-';" +
    "event.value += value.charAt(value.length - 1);" +
    "}");

textField.setValueFormat(format);

pdfDocument.getFields().add(textField);

// Bind the field to a widget and place it on the page.
RectangleF bounds = new RectangleF(120, 720, 220, 20);
TextBoxWidgetAnnotation widget = new TextBoxWidgetAnnotation(textField, bounds);

page.getAnnotations().add(widget);

Restrict User Input

Use the setKeystrokeScript(String value) method to validate characters as the user types.

The following code snippet allows users to enter only numeric characters:

FormFieldValueFormat format = new FormFieldValueFormat();

format.setKeystrokeScript(
    "var re = /^[0-9]+$/;" +
    "if (event.value != '') {" +
    "    event.rc = re.test(event.value);" +
    "}");

textField.setValueFormat(format);

Validate User Input

Use the setValidateScript(String value) method to validate the field value before it is committed. If validation fails, the script can reject the new value or notify the user.

The following code snippet uses a JavaScript validation action to ensure that users enter a valid email address:

FormFieldValueFormat format = new FormFieldValueFormat();

format.setValidateScript(
        "if (event.value.indexOf('@') == -1) {" +
                "    app.alert('Invalid email');" +
                "    event.rc = false;" +
                "}");

JavaScript Actions

The FormFieldValueFormat class supports the following JavaScript actions:

Action	Method	Description
Format	setFormatScript()	Executes before the field value is formatted.
Keystroke	setKeystrokeScript()	Executes whenever the user edits the field value.
Validate	setValidateScript()	Validates the field value before it is committed.
Calculate	setCalculateScript()	Executes when another field changes and the current field value needs to be recalculated.