Filling PDF form fields

Use form filling to set PDF field values from your application data.

Common use cases include:

  • Prepopulating onboarding and registration forms
  • Filling compliance and claim forms
  • Template-based document assembly
  • Batch form generation from CSV or database records

In this guide, you’ll fill:

  • Text fields
  • Checkboxes
  • Radio button groups
  • Combo boxes
  • List boxes
Download sample

How Nutrient helps

Nutrient Java SDK handles field access, type-specific operations, and value validation.

The SDK handles:

  • Parsing PDF form field dictionaries and identifying field types correctly
  • Managing field type casting and value format validation
  • Handling field hierarchy traversal for nested field structures
  • Complex field state management for checkboxes, radio buttons, and selections

Complete implementation

This example fills multiple form field types in one workflow:

package io.nutrient.Sample;


import io.nutrient.sdk.*;
import io.nutrient.sdk.editors.*;
import io.nutrient.sdk.editors.pdf.formfields.*;
import io.nutrient.sdk.enums.*;


public class FillPdfForm {

Create the main method as the sample entry point:

    public static void main(String[] args) {

Opening a document with form fields

Open the form document with try-with-resources, create an editor, and get the form field collection.

The collection supports iteration and lookup across field types:

        try (Document document = Document.open("input_forms.pdf")) {
            PdfEditor editor = PdfEditor.edit(document);
            PdfFormFieldCollection formFields = editor.getFormFieldCollection();

Filling a text field

Find a text field by full name, verify the type, cast it, and set the value.

In this sample:

  • The field name is Text1.
  • The type check uses PdfFormFieldType.Text.
  • The value is set with setValue("John Doe").
            PdfFormField textField = formFields.findByFullName("Text1");
            if (textField != null && textField.getFieldType() == PdfFormFieldType.Text) {
                ((PdfTextField) textField).setValue("John Doe");
            }

Checking a checkbox

Find a checkbox field, verify the type, cast it, and set the checked state.

In this sample:

  • The field name is Check1.
  • The type check uses PdfFormFieldType.CheckBox.
  • The checked state is set with setIsChecked(true).
            PdfFormField checkbox = formFields.findByFullName("Check1");
            if (checkbox != null && checkbox.getFieldType() == PdfFormFieldType.CheckBox) {
                ((PdfCheckBoxField) checkbox).setIsChecked(true);
            }

Selecting a radio button option

Find a radio group, verify the type, cast it, and select an option.

In this sample:

  • The group name is RadioGroup1.
  • The type check uses PdfFormFieldType.RadioButton.
  • The selected export value is Option2.
            PdfFormField radioGroup = formFields.findByFullName("RadioGroup1");
            if (radioGroup != null && radioGroup.getFieldType() == PdfFormFieldType.RadioButton) {
                ((PdfRadioButtonField) radioGroup).setSelectedOption("Option2");
            }

Selecting an item in a combo box

Find a combo box field, verify the type, cast it, and select one value.

In this sample:

  • The field name is Dropdown1.
  • The type check uses PdfFormFieldType.ComboBox.
  • The selected value is Germany.

Selected values match configured options exactly:

            PdfFormField comboBox = formFields.findByFullName("Dropdown1");
            if (comboBox != null && comboBox.getFieldType() == PdfFormFieldType.ComboBox) {
                ((PdfComboBoxField) comboBox).setSelectedValue("Germany");
            }

Selecting items in a list box

Find a list box field, verify the type, cast it, and select values.

In this sample:

  • The field name is List1.
  • The type check uses PdfFormFieldType.ListBox.
  • The value is selected with setSelectedValue("Technology").

With multi-select enabled, selected values match available options exactly:

            PdfFormField listBox = formFields.findByFullName("List1");
            if (listBox != null && listBox.getFieldType() == PdfFormFieldType.ListBox) {
                PdfListBoxField list = (PdfListBoxField) listBox;


                // Select an item by value
                list.setSelectedValue("Technology");
            }

Iterating and filling all fields

Iterate through all fields and apply type-based updates.

In this sample:

  • Only terminal, non-read-only fields are processed.
  • Text fields are set to "Sample Value".
  • Checkbox fields are set to checked.
            for (PdfFormField field : formFields) {
                if (field.getIsTerminal() && !field.getIsReadOnly()) {
                    PdfFormFieldType fieldType = field.getFieldType();


                    if (fieldType == PdfFormFieldType.Text) {
                        ((PdfTextField) field).setValue("Sample Value");
                    } else if (fieldType == PdfFormFieldType.CheckBox) {
                        ((PdfCheckBoxField) field).setIsChecked(true);
                    }
                }
            }

Saving the filled form

Save the output PDF and close the editor.

In this sample:

  • saveAs("output_filled_form.pdf") writes a new file.
  • editor.close() releases editor resources.
  • The catch block logs runtime failures.
            editor.saveAs("output_filled_form.pdf");
            editor.close();
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Conclusion

Use this workflow to fill PDF form fields:

  1. Open the document using try-with-resources for automatic resource cleanup.
  2. Create a PDF editor and retrieve the form field collection with getFormFieldCollection().
  3. The form field collection provides access to all form fields regardless of type.
  4. Use findByFullName() to locate specific fields by their fully qualified names (including hierarchy).
  5. Verify field types with getFieldType() before casting to specific field classes.
  6. Cast the generic PdfFormField to specific types: PdfTextField, PdfCheckBoxField, PdfRadioButtonField, PdfComboBoxField, PdfListBoxField.
  7. Fill text fields with setValue(), using string values for text input.
  8. Set checkbox states with setIsChecked() using Boolean values (true = checked, false = unchecked).
  9. Select radio button options with setSelectedOption() using export values from the option group.
  10. Select combo box items with setSelectedValue() matching predefined dropdown options exactly.
  11. Select list box items with setSelectedValue() for single or multiple selection configurations.
  12. Iterate all fields with conditional logic using getIsTerminal() and getFieldType() for batch filling operations.
  13. Save the document with saveAs() to persist all filled field values.
  14. Handle exceptions with try-catch blocks for robust error recovery in production workflows.

For related form workflows, refer to the Java SDK guides.