Organize PDF Form Fields

• Jul 13, 2026
• 3 minutes to read

Complex PDF forms can contain many related fields, such as contact information, shipping details, or billing information. Group related fields to create a logical hierarchy within the form. Groups are non-visual containers that help organize related fields and simplify programmatic access to the form structure.

To process every field regardless of its position in the hierarchy, enumerate the field collection as a flat sequence.

Group Form Fields

Create a GroupField, add related form fields to its Kids collection, and add the group to the document’s field collection.

The following code snippet creates and groups text fields:

import com.devexpress.docs.pdf.*;
import com.devexpress.system.drawing.*;
import com.devexpress.drawing.printing.DXPaperKind;

import java.nio.channels.*;
import java.nio.file.*;

public class Main {
    public static void main(String[] args) throws Exception {
        try (PdfDocument pdfDocument = new PdfDocument()) {
            // Add an A4 page to the document.
            Page page = pdfDocument.getPages().add(DXPaperKind.A4);

            // Create text fields.
            TextBoxField firstNameField = new TextBoxField("FirstName");
            TextBoxField lastNameField = new TextBoxField("LastName");

            firstNameField.setValue("John");
            lastNameField.setValue("Doe");

            TextBoxWidgetAnnotation widget1 =
                    new TextBoxWidgetAnnotation(
                        firstNameField,
                        new RectangleF(120, 720, 220, 20));
            page.getAnnotations().add(widget1);

            RectangleF bounds = new RectangleF(120, 720, 220, 20);
            TextBoxWidgetAnnotation widget2 =
                    new TextBoxWidgetAnnotation(
                            lastNameField,
                            new RectangleF(120, 690, 220, 20));
            page.getAnnotations().add(widget2);

            // Create a group.
            GroupField group = new GroupField("Contact");

            // Add fields to the group.
            group.getKids().add(firstNameField);
            group.getKids().add(lastNameField);

            // Add the group to the document.
            pdfDocument.getFields().add(group);

            // Save the document.
            try (WritableByteChannel channel =
                     FileChannel.open(Path.of("result.pdf"),
                         StandardOpenOption.CREATE,
                         StandardOpenOption.WRITE,
                         StandardOpenOption.TRUNCATE_EXISTING)) {

                pdfDocument.save(channel);
            }
        }
    }
}

A group field is a logical container and does not appear on the page. Child fields remain associated with their own widget annotations.

Find a Field’s Parent Group

Call the findParent(FormField field) method to check whether a form field belongs to a group and to obtain its parent group.

The following code snippet obtains the parent group of a form field:

// Find a form field.
FormField field = pdfDocument.getFields().findByName("FirstName");

// Get the parent group.
GroupField group = pdfDocument.getFields().findParent(field);

if (group != null) {
    System.out.println(group.getName());
}

Iterate Through Fields in a Group

A group field stores its child fields in the kids collection. Use the getKids() method to access and iterate through this collection and process all fields that belong to the group.

The following code snippet iterates through all fields in the Customer group:

// Find the group.
GroupField contactGroup = (GroupField)pdfDocument.getFields().findByName("Contact");

// Iterate through the fields in the group.
for (FormField field : contactGroup.getKids()) {
    System.out.println(field.getName());
}

If a group contains nested groups, call the parent group’s toFlatIterable() method to enumerate all descendant fields. For example, use this method to validate, update, or export only fields that belong to a specific form section.

// Iterate through all fields in the group hierarchy.
for (FormField field : contactGroup.getKids().toFlatIterable()) {
    System.out.println(field.getName());
}

Flatten the Form Field Collection

Call the toFlatIterable() method to enumerate all form fields in the document without manually traversing the group hierarchy.

The following code snippet iterates through all form fields in the document:

// Iterate through all form fields, including fields in groups.
for (FormField field : pdfDocument.getFields().toFlatIterable()) {
    System.out.println(field.getName());
}