How to add click event to reset the PDFForm?

[ptthanh0606]

The API document for PDFButton states that I can reset the form on PDF button click; however, I am unsure how to achieve this. Sorry, I have tried my best in the documentation and PDF-Lib GitHub page, and found absolutely nothing...The document should include a demonstration on how to add an event to a PDFButton, I think.

[fstandhartinger]

pdf-lib has no high-level method for this, but you can do it with the low-level API. A button does something when its widget annotation has an action in its /A entry. The standard action for this is /S /ResetForm (PDF 1.7 spec, §12.7.5.3). No JavaScript is needed.

import { PDFDocument, PDFName, PDFHexString } from 'pdf-lib';

const pdfDoc = await PDFDocument.create();
const page = pdfDoc.addPage([400, 300]);
const form = pdfDoc.getForm();

const name = form.createTextField('name');
name.addToPage(page, { x: 90, y: 240, width: 200, height: 22 });
const city = form.createTextField('city');
city.addToPage(page, { x: 90, y: 200, width: 200, height: 22 });

// fields: optional array of PDFFields. Leave it out to reset the whole form.
function addResetAction(button, fields) {
  const action = { Type: 'Action', S: 'ResetForm' };
  if (fields) {
    // Use field NAMES here, not f.ref (see note 2)
    action.Fields = fields.map((f) => PDFHexString.fromText(f.getName()));
  }
  const actionRef = pdfDoc.context.register(pdfDoc.context.obj(action));
  for (const widget of button.acroField.getWidgets()) {
    widget.dict.set(PDFName.of('A'), actionRef);
  }
}

const resetAll = form.createButton('resetAll');
resetAll.addToPage('Reset all', page, { x: 90, y: 110, width: 90, height: 24 });
addResetAction(resetAll);

const resetName = form.createButton('resetName');
resetName.addToPage('Reset name', page, { x: 200, y: 110, width: 90, height: 24 });
addResetAction(resetName, [name]); // resets only "name"

const bytes = await pdfDoc.save();

Things I found while testing it:

1. "Reset" means "go back to the default value (/DV)", not "clear". pdf-lib's setText() only sets /V, so by default a reset empties the field. If a field should go back to a preset value, give it a /DV, e.g. city.acroField.dict.set(PDFName.of('DV'), PDFString.of('Berlin')).
2. Use names, not refs, in /Fields. The spec allows either. But pdf-lib stores every field as a parent field dictionary with a separate widget as its kid. If you pass name.ref, which is the parent, both pdf.js and PDFium ignore it and nothing resets. With the field's fully qualified name as a string, both reset it correctly.
3. To reset every field except the listed ones, add Flags: 1 to the action dictionary (bit 1 = Include/Exclude). I tested it: in both engines name kept its value and everything else was reset.

What I tested, with pdf-lib 1.17.1: I built the PDF above, plus a checkbox and a /DV on city. Then I filled the fields and clicked the buttons in two engines:

	pdf.js 4.10 (Firefox's viewer)	PDFium 153 (Chrome/Edge's engine)
"Reset all"	name → empty, city → Berlin (its /DV), checkbox → unchecked	same
"Reset name" (/Fields by name)	only name → empty	same
"Reset name" (/Fields by name.ref)	nothing happens	nothing happens

I did not test Adobe Acrobat.

Disclosure: I work on a hosted HTML→PDF API. It has nothing to do with this answer and isn't linked here. I wrote this with AI assistance, and the results in the table are from actually running it.