Workflow 9 min read 18 October 2026

Creating PDF Forms: AcroForms vs XFA, Field Types, and Submission

PDF forms come in two flavours — AcroForms (the ISO-standard model supported everywhere) and XFA (Adobe's XML-based format, now deprecated). This guide covers building AcroForms from scratch: field types, calculation scripts, validation, submission methods, and how to make forms work across Adobe Reader, browsers, and mobile PDF viewers.

PDF forms allow users to fill in data directly within the document — entering text, selecting options, ticking checkboxes, and submitting the completed form to a server or saving it locally. They are used for applications, tax returns, government registrations, satisfaction surveys, contracts, and countless other data-collection scenarios. PDF has two form technologies: AcroForms, the ISO 32000-standard model that works everywhere, and XFA (XML Forms Architecture), Adobe's XML-based dynamic forms format that is now deprecated and not supported outside Adobe's own products. This guide focuses exclusively on AcroForms — the technology you should use for any new form development.

AcroForms: the PDF form model

An AcroForm document has a /AcroForm dictionary in the document catalogue containing: /Fields — An array of indirect references to the top-level form field objects (a field hierarchy — fields can have parent–child relationships for radio button groups and composite fields). /DA (Default Appearance) — A PDF content stream fragment specifying the default font and colour for form field text. /DR (Default Resources) — A resource dictionary providing fonts and colour spaces referenced by the DA string. /NeedAppearances — Boolean flag indicating whether the viewer should regenerate appearance streams for all fields when opening. Set to true if you want the viewer to honour the DA styling; set to false (or omit) if you have pre-generated appearance streams. Form field types (/FT in field dictionaries): - /Tx — Text field. Single-line or multi-line (/Ff bit 13 set for multiline), password (bit 14), rich text (bit 26), comb (bit 25 for fixed-width character boxes like date fields). - /Btn — Button. Pushbutton (bit 17 set), checkbox (no bits), or radio button group (bit 16 set). Radio buttons are grouped by shared parent field. - /Ch — Choice field. List box or combo box (bit 18 set for combo). Options defined in /Opt array. - /Sig — Signature field. Displays a digital signature appearance. The signature value is a cryptographic signature dictionary populated when the user signs. Each field is associated with a Widget annotation on the page that provides its visual representation and interaction rectangle.

Field properties, validation, and calculation

AcroForms support JavaScript-based validation, calculation, and formatting — making it possible to create forms with computed totals, field validation rules, and conditional logic. Field actions — Form field dictionaries can carry several /AA (Additional Actions) entries: - /K — Keystroke action: runs JavaScript on each keystroke in a text field. Used for format masks (phone numbers, dates). - /V — Validate action: runs JavaScript when the field loses focus. Used for range checks, format validation. - /C — Calculate action: runs JavaScript to compute a field value from other fields. Used for totals, computed quantities. - /F — Format action: runs JavaScript to format the displayed value (currency formatting, date display). JavaScript calculation example — To sum two fields (qty and price) into a total field, the total field's calculate action runs: event.value = (Number(this.getField("qty").value) * Number(this.getField("price").value)).toFixed(2); Calculation order — The /CO (calculation order) array in the AcroForm dictionary specifies the order in which fields with calculation actions are evaluated. Fields are computed in this order whenever any field value changes. Security note — PDF JavaScript runs inside a sandboxed JavaScript environment in Adobe Reader. However, PDF JavaScript has a significant security history. Avoid JavaScript that reads/writes files, makes network requests beyond form submission, or spawns processes. Keep form scripts to simple arithmetic and validation.

Form submission and data formats

Completed AcroForms can submit data to a web server or save locally in several ways: Submit button action — A pushbutton with a /SubmitForm action sends form data to a URL. The action specifies: - /F — The submission URL. - /Flags — Controls what is submitted: bit 1 = include/exclude field list; bit 3 = submit as HTML form data (FDF if unset); bit 4 = use HTTP POST; bit 6 = submit as XFDF; bit 9 = submit the entire PDF document. FDF (Forms Data Format) — FDF is a lightweight format containing only form field values (not the full PDF). When a form is submitted as FDF, the server receives a small file that can be imported back into the PDF form. FDF is the default AcroForm submission format. XFDF (XML Forms Data Format) — XML-based equivalent of FDF. More interoperable than FDF (it is XML), easier to parse on the server side. Preferred for new integrations. PDF submission — Submitting the entire PDF (Flags bit 9) sends the complete annotated/filled PDF to the server. Larger than FDF/XFDF but self-contained. Useful when the server needs to archive or display the filled form. HTML form submission (key-value pairs) — Submitting as HTML form data sends URL-encoded or multipart form data, compatible with standard web server form processing. The simplest integration if the server already handles HTML form submissions. Print and save locally — Many PDF forms are not submitted online — they are filled and printed, or saved as a filled PDF. For print-and-sign workflows, ensuring the form fields are printable (the Print flag set in /Ff) and the Reset/Clear button is available helps users.

Creating AcroForms: tools and libraries

Adobe Acrobat Pro — Tools > Prepare Form. Acrobat can auto-detect form fields in a PDF (useful for PDFs created from scanned or designed forms) and creates interactive fields over them. Manual field placement, resizing, and property editing via the Properties dialog. Acrobat Pro remains the most complete form authoring environment. LibreOffice Writer/Draw — Supports PDF form export with basic field types. Limited compared to Acrobat Pro but free and cross-platform. Tools > Form > Form Controls to insert fields. iText 7 (Java/C#) — Full programmatic AcroForm creation. PdfFormField classes cover all field types. Example:

PdfTextFormField textField = PdfFormField.createText(pdf, new Rectangle(50, 700, 200, 20), "firstname", "");
form.addField(textField);

iText is the standard for generating PDF forms programmatically from data. PDFLib — Full form creation API in C, Java, .NET, and PHP. Strong support for multilingual forms and complex layouts. pdf-lib (JavaScript) — pdf-lib.js.org. Browser and Node.js PDF library with AcroForm support. pdfDoc.getForm().createTextField('name') creates a text field. Good for client-side or serverless PDF form generation. Accessibility for forms — Every form field must have a tooltip (/TU entry) providing an accessible name. The logical tab order must match visual layout. Required fields should be indicated both visually and programmatically. See PDF accessibility remediation for form-specific accessibility requirements.

Frequently asked questions

What is the difference between AcroForms and XFA forms?

AcroForms is the PDF-native form technology defined in ISO 32000. It stores form fields as widget annotations in the PDF page structure, works in all PDF viewers (Adobe Reader, Chrome, Firefox, Preview, mobile viewers), and is fully supported by all PDF libraries. XFA (XML Forms Architecture) is Adobe's proprietary XML-based form format introduced in PDF 1.5. XFA forms store their entire definition in an XML stream embedded in the PDF — the PDF page content is secondary. XFA is only supported in Adobe Reader/Acrobat (not in Chrome, Firefox, Preview, or most mobile PDF viewers) and was formally deprecated by Adobe in 2021. New form development should use AcroForms exclusively. If you have existing XFA forms, they need to be rebuilt as AcroForms to work in modern PDF viewers.

How do I prefill a PDF form programmatically?

With pdf-lib (JavaScript/Node.js): const form = pdfDoc.getForm(); form.getTextField("firstname").setText("Jane"); form.getCheckBox("agree").check(); then save the PDF. With iText 7 (Java): PdfAcroForm form = PdfAcroForm.getAcroForm(pdf, false); form.getField("firstname").setValue("Jane"); With PyMuPDF: doc = fitz.open("form.pdf"); page = doc[0]; for widget in page.widgets(): if widget.field_name == "firstname": widget.field_value = "Jane"; widget.update(); doc.save("filled.pdf"). After filling fields programmatically, set NeedAppearances to true in the AcroForm dictionary (or pre-generate appearance streams) to ensure the filled values are visible in all viewers — some viewers will not display field values unless appearance streams are present.

Can I make a PDF form that submits data to my website?

Yes. Create a Submit button (pushbutton) with a SubmitForm action pointing to your server URL. In Acrobat Pro: insert a button field, open Properties > Actions > Select Trigger: Mouse Up > Select Action: Submit a Form > Add. Set the URL, choose XFDF or HTML as the format. On the server side, handle the incoming XFDF (XML) or FDF or HTML form data. XFDF is easiest to parse — it is XML with a standard schema. For Node.js: use the formidable or busboy package for multipart POST. For Python/Django or Flask: use request.POST for HTML form format or parse the XFDF body with an XML parser. Note: PDF form submission works well in Adobe Reader but may not function in all browser PDF viewers (Chrome's viewer does not support PDF form submission). For broad compatibility, consider using HTML forms for web-based data collection and reserve PDF forms for locally-filled or Adobe Reader-specific workflows.

Try it yourself

Everything in this article can be done directly in the free PDFTheGuide editor — no account required.

Fill PDF form Edit PDF Sign PDF Open editor