How to Work with AcroForm Fields in TypeScript

This guide shows how to add and flatten AcroForm fields with Aspose.PDF FOSS for TypeScript. Document.Form exposes one Add* method per field type — text, checkbox, radio group, combo box, list box, and push button — each returning a typed field handle. It requires Node.js 22 or later.

Step-by-Step Guide

Step 1: Install the Package

asposefoss/pdf is not yet published — build from source until it ships. See the project README for build instructions.

Verify the installation by importing the Document class in a new TypeScript file — this line should resolve without error once the package is installed:

import { Document } from '@asposefoss/pdf';

Step 2: Import Required Classes

Import Document to open the file and reach doc.Form, the entry point for every field method used below:

import { Document } from '@asposefoss/pdf';

Step 3: Add a Text Field and Checkbox

Form.AddTextField(init) and Form.AddCheckbox(init) both take a page number, a rect, a unique name, and styling options:

const doc = Document.OpenFile('form-template.pdf');
const form = doc.Form;
const pageNum = doc.Pages[0].Number;

form.AddTextField({
  page: pageNum, rect: [200, 670, 450, 690], name: 'FullName', value: 'Alice Sample',
  borderColor: [0.1, 0.15, 0.4], font: 'Helvetica', fontSize: 12,
});

form.AddCheckbox({
  page: pageNum, rect: [200, 630, 218, 648], name: 'Subscribe',
  checked: true, borderColor: [0.1, 0.15, 0.4],
});

Step 4: Add a Radio Group, Combo Box, and List Box

Form.AddRadioGroup(init) takes a single name shared by every option in its options array, each with its own rect and export value. Form.AddComboBox(init) and Form.AddListBox(init) take an options array of { export, display } pairs; list boxes additionally support multiSelect:

form.AddRadioGroup({
  name: 'Plan', selected: 'Pro',
  options: [
    { page: pageNum, rect: [200, 590, 218, 608], export: 'Basic' },
    { page: pageNum, rect: [290, 590, 308, 608], export: 'Pro' },
  ],
});

form.AddComboBox({
  page: pageNum, rect: [200, 550, 350, 570], name: 'Country', value: 'US',
  options: [
    { export: 'US', display: 'United States' },
    { export: 'UK', display: 'United Kingdom' },
  ],
});

form.AddListBox({
  page: pageNum, rect: [200, 410, 350, 510], name: 'Interests',
  multiSelect: true, value: ['pdf'],
  options: [
    { export: 'pdf', display: 'PDF Engineering' },
    { export: 'crypto', display: 'Cryptography' },
  ],
});

Step 5: Add a Push Button

Form.AddPushButton(init) takes a caption and an action describing what the button does when clicked — for example, submitting the form’s data to a URL:

form.AddPushButton({
  page: pageNum, rect: [200, 320, 320, 388], name: 'Submit',
  caption: 'Submit',
  action: { type: 'submit', url: 'https://example.com/submit', format: 'fdf' },
});

Step 6: Flatten Form Fields

Every field handle returned by an Add* call has a Flatten() method that bakes its current value into the page’s content stream and removes it from the interactive AcroForm:

const tb = form.AddTextField({
  page: pageNum, rect: [210, 660, 460, 680], name: 'FlattenName', value: 'Alice Sample',
});
tb.Flatten(); // -> number; bakes the value, unwires the field from /AcroForm

doc.WriteTo('flattened.pdf');

Common Issues and Fixes

A field does not appear on the intended page. page in the field’s init object is that page’s own page number, not an array index — confirm it against page.Number on the target Page.

Radio button options are not mutually exclusive. Every option in Form.AddRadioGroup()’s options array must share the group’s single name — mixing field names creates independent checkboxes instead of a radio group.

A flattened field’s value does not appear in the saved file. Save the document (doc.WriteTo() / doc.Save()) after calling Flatten() — the change only exists in memory until the file is written back out.

A combo box shows the export value instead of the display text. The appearance draws display; the field’s stored value (/V) is export — confirm both are set for every option, not just one.

Frequently Asked Questions

Can I read a field’s current value after the form is filled?

Yes — read the field handle’s Value property, or iterate doc.Form.Fields to inspect every field on the document.

What is the difference between `Flatten()` on a field and on an annotation?

Both bake interactive content into static page content and remove it from its respective collection — a field’s Flatten() removes it from /AcroForm, while an annotation’s Flatten() (covered in the Annotations guide) removes it from the page’s /Annots.

Can a list box allow multiple selections?

Yes — set multiSelect: true on Form.AddListBox()’s init object and pass an array to value.

Does a push button need an action to be useful?

An action (for example { type: 'submit', url, format }) is what makes the button do something when clicked; without one it renders but has no behavior wired up.