How to Fill PDF Form Fields in Node.js

Updated: August 2, 2026

Filling PDF forms programmatically in Node.js lets you automate document workflows: from populating application forms with database records to generating personalized certificates at scale. IronPDF for Node.js provides a straightforward API for loading existing PDFs, writing values into form fields, and saving the completed documents without leaving your JavaScript environment.

This guide covers the full workflow: installing the package, applying a license key, filling text fields, checkboxes, dropdowns, and radio buttons, flattening form fields to lock values, and saving the output. All code examples use async/await and the @ironsoftware/ironpdf package.

Quickstart: Fill a PDF Form in Node.js

Install the package, then load and fill a form in a few lines:

npm install @ironsoftware/ironpdf

npm install @ironsoftware/ironpdf

SHELL

const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = "YOUR-LICENSE-KEY-HERE";

(async () => {
    const pdf = await PdfDocument.fromFile("./form.pdf");
    await pdf.setFormFieldValue("firstName", "Jane");
    await pdf.setFormFieldValue("email", "jane@example.com");
    await pdf.saveAs("./filled-form.pdf");
})();

const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = "YOUR-LICENSE-KEY-HERE";

(async () => {
    const pdf = await PdfDocument.fromFile("./form.pdf");
    await pdf.setFormFieldValue("firstName", "Jane");
    await pdf.setFormFieldValue("email", "jane@example.com");
    await pdf.saveAs("./filled-form.pdf");
})();

JavaScript

Minimal Workflow (5 steps)

Install IronPDF: npm install @ironsoftware/ironpdf
Set your license key via IronPdfGlobalConfig.getConfig().licenseKey
Load the existing PDF with PdfDocument.fromFile(path)
Set each field value with await pdf.setFormFieldValue(fieldName, value)
Save the result with await pdf.saveAs(outputPath)

What Prerequisites Do I Need to Fill PDF Forms in Node.js?

Before running the code examples below, confirm that three things are in place: a supported Node.js version, an IronPDF license key, and the IronPdfEngine binary.

Node.js version: IronPDF requires Node.js 18 or higher. Download the current LTS release from the official Node.js website. The library uses Node.js asynchronous I/O for all PDF operations, so async/await or Promise chaining is the standard pattern throughout. Older versions of Node.js are not supported because the package depends on native ESM and async_hooks features that require Node.js 18+.

License key: An active IronPDF license key unlocks the full API. Start a free trial to get a key for development and testing, or purchase a license for production use. For deployment options (environment variables, configuration files, secrets managers), see the Using License Keys guide.

IronPdfEngine: The Node.js package includes IronPdfEngine, a cross-platform rendering engine that handles the actual PDF manipulation. Setup and platform-specific notes (Windows, Linux, macOS) are in the Use IronPdfEngine documentation.

How Do I Set the License Key in Node.js Code?

Apply the license key once at application startup, before any PdfDocument calls:

const { IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

// Apply once at startup -- before any PdfDocument operations
IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

const { IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

// Apply once at startup -- before any PdfDocument operations
IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

JavaScript

Storing the key in an environment variable (as shown above with process.env.IRONPDF_LICENSE_KEY) keeps credentials out of source control. The Get Started Overview covers additional initialization patterns for different deployment environments.

How Do I Install IronPDF for Node.js?

Installing IronPDF for Node.js takes a single npm command. Run it in your project directory:

npm install @ironsoftware/ironpdf

npm install @ironsoftware/ironpdf

SHELL

The package ships with TypeScript type declarations, so TypeScript projects get full IntelliSense support without a separate @types package. Platform-specific binaries for Windows, Linux, and macOS are downloaded automatically during installation. The @Iron Software/ironpdf package on npm lists all published versions and peer dependencies.

Please note: For TypeScript projects, the included .d.ts declarations mean IntelliSense works out of the box in VS Code and other editors that support TypeScript language services.

For instructions on adding IronPDF to an existing monorepo or Docker-based workflow, see the IronPDF for Node.js documentation.

How Do I Fill PDF Forms Programmatically?

Loading a PDF and writing values into its form fields requires three async calls: PdfDocument.fromFile(), setFormFieldValue(), and saveAs(). The example below fills a multi-field application form and optionally flattens it so the values cannot be changed after delivery.

What Does a Complete Form-Filling Example Look Like?

The following example loads a PDF with several field types, fills them, and saves the result. For a focused look at creating forms rather than filling them, see the PDF Forms examples page.

const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

async function fillApplicationForm() {
    // Load the PDF containing form fields
    const pdf = await PdfDocument.fromFile("./forms/application-form.pdf");

    // Discover available field names before filling
    const fieldNames = await pdf.getFormFieldNames();
    console.log("Form fields:", fieldNames);

    // Text fields
    await pdf.setFormFieldValue("firstName", "Jane");
    await pdf.setFormFieldValue("lastName", "Doe");
    await pdf.setFormFieldValue("email", "jane.doe@example.com");
    await pdf.setFormFieldValue("phone", "+1-555-987-6543");

    // Date field
    await pdf.setFormFieldValue("dateOfBirth", "03/22/1988");

    // Checkbox fields -- pass "true" or "false" as strings
    await pdf.setFormFieldValue("agreeToTerms", "true");
    await pdf.setFormFieldValue("subscribeNewsletter", "false");

    // Dropdown / select field
    await pdf.setFormFieldValue("country", "United States");

    // Multi-line text area
    await pdf.setFormFieldValue("comments", "Application submitted via automated workflow.");

    // Flatten the form to lock values -- prevents further editing
    // await pdf.flattenAllFormFields();

    await pdf.saveAs("./output/filled-application.pdf");
    console.log("Form saved.");
}

fillApplicationForm().catch(console.error);

const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

async function fillApplicationForm() {
    // Load the PDF containing form fields
    const pdf = await PdfDocument.fromFile("./forms/application-form.pdf");

    // Discover available field names before filling
    const fieldNames = await pdf.getFormFieldNames();
    console.log("Form fields:", fieldNames);

    // Text fields
    await pdf.setFormFieldValue("firstName", "Jane");
    await pdf.setFormFieldValue("lastName", "Doe");
    await pdf.setFormFieldValue("email", "jane.doe@example.com");
    await pdf.setFormFieldValue("phone", "+1-555-987-6543");

    // Date field
    await pdf.setFormFieldValue("dateOfBirth", "03/22/1988");

    // Checkbox fields -- pass "true" or "false" as strings
    await pdf.setFormFieldValue("agreeToTerms", "true");
    await pdf.setFormFieldValue("subscribeNewsletter", "false");

    // Dropdown / select field
    await pdf.setFormFieldValue("country", "United States");

    // Multi-line text area
    await pdf.setFormFieldValue("comments", "Application submitted via automated workflow.");

    // Flatten the form to lock values -- prevents further editing
    // await pdf.flattenAllFormFields();

    await pdf.saveAs("./output/filled-application.pdf");
    console.log("Form saved.");
}

fillApplicationForm().catch(console.error);

JavaScript

After calling getFormFieldNames(), the returned array tells you which field names the PDF author used. This is the fastest way to avoid typos in field names when integrating with forms you did not create.

Tips: Call getFormFieldNames() once during development to print the exact field names in your PDF. Hardcoding the wrong name is the most common cause of fields appearing empty after setFormFieldValue().

How Do I Handle Different Form Field Types?

IronPDF supports the standard AcroForm field types: text boxes, checkboxes, radio buttons, dropdowns, list boxes, and signature fields. The setFormFieldValue() method accepts string values for all types; for checkbox and radio fields, the accepted values depend on the specific field definition in the PDF.

The table below shows the value format for each field type:

PDF AcroForm field types and their accepted value formats

Field Type	Value Format	Example
Text / Multiline	Any string	`"Jane Doe"`
Checkbox	`"true"` or `"false"`	`"true"`
Radio Button	Export value of the option	`"Female"`
Dropdown (Combo)	Display text of the option	`"United States"`
List Box (multi-select)	Array of strings	`["Option1", "Option2"]`
Date / Numeric	String representation	`"2024-06-15"`

How Do Checkboxes and Radio Buttons Work?

Checkboxes accept "true" to check and "false" to uncheck. Radio buttons accept the export value of the option to select -- the exported string is usually visible in the PDF's field properties and is distinct from the display label.

const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

async function handleFieldTypes() {
    const pdf = await PdfDocument.fromFile("./forms/complex-form.pdf");

    // Radio button -- use the field's export value, not its display label
    await pdf.setFormFieldValue("gender", "Female");

    // Checkbox
    await pdf.setFormFieldValue("termsAccepted", "true");

    // Dropdown
    await pdf.setFormFieldValue("preferredContact", "Email");

    // Numeric field -- pass the number as a string
    await pdf.setFormFieldValue("invoiceAmount", "1250.00");

    // Date picker
    await pdf.setFormFieldValue("appointmentDate", "2024-06-15");

    await pdf.saveAs("./output/complex-form-filled.pdf");
}

handleFieldTypes().catch(console.error);

const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

async function handleFieldTypes() {
    const pdf = await PdfDocument.fromFile("./forms/complex-form.pdf");

    // Radio button -- use the field's export value, not its display label
    await pdf.setFormFieldValue("gender", "Female");

    // Checkbox
    await pdf.setFormFieldValue("termsAccepted", "true");

    // Dropdown
    await pdf.setFormFieldValue("preferredContact", "Email");

    // Numeric field -- pass the number as a string
    await pdf.setFormFieldValue("invoiceAmount", "1250.00");

    // Date picker
    await pdf.setFormFieldValue("appointmentDate", "2024-06-15");

    await pdf.saveAs("./output/complex-form-filled.pdf");
}

handleFieldTypes().catch(console.error);

JavaScript

Multi-select list box fields follow the same pattern. When a field allows multiple selections, pass an array of strings rather than a single value. Signature fields can receive a base64-encoded image string representing the signature graphic.

Important: If setFormFieldValue() does not appear to change a field's value, check that the field name matches exactly -- PDF field names are case-sensitive. Use getFormFieldNames() to list the actual names in the document.

How Do I Flatten PDF Form Fields After Filling?

Flattening a PDF form merges all field values into the static page content, removing the interactive layer. The resulting document cannot be edited further, which prevents accidental changes during distribution and ensures consistent rendering across all PDF viewers.

Call flattenAllFormFields() on the loaded document after setting all field values and before saving:

const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

async function fillAndFlattenForm() {
    const pdf = await PdfDocument.fromFile("./forms/contract.pdf");

    // Fill the required fields
    await pdf.setFormFieldValue("signerName", "Jane Doe");
    await pdf.setFormFieldValue("signatureDate", "2024-06-15");
    await pdf.setFormFieldValue("agreementAccepted", "true");

    // Flatten -- converts interactive fields to static content
    await pdf.flattenAllFormFields();

    await pdf.saveAs("./output/contract-signed.pdf");
    console.log("Contract flattened and saved.");
}

fillAndFlattenForm().catch(console.error);

const { PdfDocument, IronPdfGlobalConfig } = require("@ironsoftware/ironpdf");

IronPdfGlobalConfig.getConfig().licenseKey = process.env.IRONPDF_LICENSE_KEY;

async function fillAndFlattenForm() {
    const pdf = await PdfDocument.fromFile("./forms/contract.pdf");

    // Fill the required fields
    await pdf.setFormFieldValue("signerName", "Jane Doe");
    await pdf.setFormFieldValue("signatureDate", "2024-06-15");
    await pdf.setFormFieldValue("agreementAccepted", "true");

    // Flatten -- converts interactive fields to static content
    await pdf.flattenAllFormFields();

    await pdf.saveAs("./output/contract-signed.pdf");
    console.log("Contract flattened and saved.");
}

fillAndFlattenForm().catch(console.error);

JavaScript

Flattening is appropriate for final deliveries -- contracts after signing, certificates after issuance, or invoices after approval. For documents that need further review before finalization, skip flattenAllFormFields() and save without it.

Warning: Flattening is irreversible on the saved copy. Keep the original, unfilled PDF as a template if you need to re-generate the document.

What Are Common Use Cases for PDF Form Automation?

Automated form filling removes manual data entry from high-volume document workflows. The following scenarios cover the most frequent patterns developers implement with IronPDF.

Application processing: Pull applicant data from a database or REST API and populate PDF forms for financial services, insurance, or government intake workflows. Combine filled forms using the Merge PDFs example to produce a single multi-page submission packet.

Invoice and receipt generation: Fill invoice templates with line-item data, customer details, and calculated totals. Add page headers and footers using the techniques shown in the HTML Headers and Footers example.

Certificate and credential generation: Personalize certificate templates with recipient names, completion dates, and course titles. Add security using the Digital Signatures example to prevent tampering after issuance. The PDF/A standard is commonly required for long-term archival of certificates in regulated industries.

Report generation: Fill report templates with analytics data or survey results. For cases where you need to build the PDF layout from scratch rather than fill an existing form, see the HTML to PDF tutorial.

What Are the Next Steps for PDF Form Filling in Node.js?

This guide demonstrated loading a PDF, filling text fields, checkboxes, dropdowns, and radio buttons, flattening the form to lock values, and saving the completed document. The same PdfDocument instance supports further operations -- add digital signatures, compress the output, or extract text -- without reloading the file.

Start a free trial to test IronPDF in your project, or view licensing options to find the plan that fits your deployment.

Ready to see what else you can do? Check out the full Node.js tutorial collection here: HTML to PDF in Node.js

Frequently Asked Questions

What is required to fill PDF forms using IronPDF in Node.js?

To fill PDF forms using IronPDF in Node.js, you need a supported Node.js version (18 or higher), an active IronPDF license key, and the IronPdfEngine binary. These components allow you to load PDFs, modify form fields, and save the updated documents.

How do I install IronPDF for Node.js?

You can install IronPDF for Node.js by running the command `npm install @ironsoftware/ironpdf` in your project directory. This package comes with TypeScript type declarations, offering full IntelliSense support.

How can I fill text fields in a PDF form using IronPDF?

You can fill text fields in a PDF form using IronPDF by loading a PDF document with `PdfDocument.fromFile()` and setting the field values using the `setFormFieldValue()` method. Finally, save the updated PDF using `pdf.saveAs(outputPath)`.

What types of PDF form fields can IronPDF handle?

IronPDF supports filling various form fields including text boxes, checkboxes, radio buttons, dropdowns, list boxes, and signature fields. Each type requires specific value formats.

How do checkboxes and radio buttons work in IronPDF?

In IronPDF, checkboxes are filled with the value 'true' for checked and 'false' for unchecked. Radio buttons are filled using the export value of the option to select it, which is typically found in the PDF field properties.

What is the purpose of flattening PDF forms?

Flattening PDF forms merges filled field values into the static page content, making the document uneditable. This ensures consistent display across all readers and prevents amendments after distribution.

How can IronPDF be used for automated PDF form filling?

IronPDF can automate form filling by integrating with databases or APIs to populate PDFs with user data in workflows such as application processing, invoice generation, and certificate issuance.

What is the benefit of storing the IronPDF license key in an environment variable?

Storing the IronPDF license key in an environment variable helps to keep your credentials secure and out of source control, thus enhancing application security.

Can IronPDF handle multi-line text fields in PDF forms?

Yes, IronPDF can handle multi-line text fields by passing the desired text string to the `setFormFieldValue()` method. This is useful for extensive input like comments or descriptions.

What should I do if form fields appear empty after using IronPDF?

If form fields appear empty after using IronPDF, ensure the field names match exactly. Field names are case-sensitive, so use `pdf.getFormFieldNames()` to list and verify the actual field names.

Curtis Chau

Chat with engineering team now

Technical Writer

Curtis Chau holds a Bachelor’s degree in Computer Science (Carleton University) and specializes in front-end development with expertise in Node.js, TypeScript, JavaScript, and React. Passionate about crafting intuitive and aesthetically pleasing user interfaces, Curtis enjoys working with modern frameworks and creating well-structured, visually appealing manuals.

...