When you click a button in a PDF form and it calculates a total — that's a trigger (MouseUp on the button field) paired with an action (a JavaScript function that reads field values and writes the sum). Every interactive behaviour in a PDF is an event-action pair. Triggers define when something happens: when the document opens, when a user types into a field, when they hover over a region, when they visit a page. Actions define what happens: navigate to page 5, open a URL, submit the form data to a server, calculate a formula, show or hide a field. Together they power every form, button, link, and automation in interactive PDF documents.
What Are PDF Actions and Triggers?
In the PDF specification, an action is an object that defines an operation to be performed. A trigger is a named event that causes an action to fire. The relationship is defined in the PDF's interactive features dictionary — a field, annotation, page, or the document itself can carry an action trigger dictionary that maps named events to action objects.
The key action types defined in the PDF specification are:
- JavaScript (JS) — Execute a JavaScript function. The most powerful and widely used action type.
- GoTo — Navigate to a specific page, named destination, or coordinate within the current document.
- GoToR — Navigate to a location in a remote (different) PDF file.
- URI — Open a URL in the system's default web browser.
- SubmitForm — Send form field data to a URL via HTTP POST/GET.
- ResetForm — Reset all form fields to their default values.
- ImportData — Import FDF/XFDF data into the document's form fields.
- Named — Execute a pre-defined named viewer operation (Print, NextPage, PrevPage, etc.).
- Launch — Open an external application or file. Considered a security risk; disabled in many viewers.
- Rendition — Control media playback (video, audio) in PDF rich media annotations.
Security note: PDF JavaScript and Launch actions are the primary vectors for PDF-based malware. Modern viewers sandbox or restrict these actions. PDF/A files are required to have no actions at all — a key reason they are safer for archiving than regular interactive PDFs.
PDF Triggers: When Actions Fire
| Trigger Name | When It Fires | Applicable To |
|---|---|---|
| OpenAction | When the document is opened | Document (catalog level) |
| /O (Open) | When a page is visited | Page, Annotation |
| /C (Close) | When moving away from this page | Page, Annotation |
| MouseUp | Mouse button released over element | Form field, Annotation |
| MouseDown | Mouse button pressed on element | Form field, Annotation |
| MouseEnter | Cursor enters element boundary | Form field, Annotation |
| MouseExit | Cursor leaves element boundary | Form field, Annotation |
| OnFocus | Element receives keyboard focus | Form field |
| OnBlur | Element loses focus | Form field |
| Keystroke | Each keypress in text field | Text form field |
| Format | Format field value for display | Text form field |
| Validate | Validate value when field is committed | Text form field |
| Calculate | Recalculate when any field value changes | Text form field |
Real-World Examples
Interactive Tax Return: Calculate and Validate
A government tax authority distributes an interactive PDF tax return. Every numeric text field carries a Keystroke trigger that restricts input to digits only. A Calculate trigger on the "Total Income" field fires whenever any income field changes — summing Line 1 through Line 6 automatically. A Validate trigger on the submission button checks that all required fields are filled and all values are within legal bounds. On submit, a SubmitForm action sends the complete FDF data to the authority's server via HTTPS POST. The taxpayer never leaves the PDF.
Sales Proposal: OpenAction Navigation
A sales team creates a PDF proposal that always opens on the executive summary page, not page 1. An OpenAction GoTo navigates directly to the named destination "executive-summary" when the file is opened. A button on each section footer reads "Back to Summary" — a MouseUp GoTo action returning to the same destination. Navigation buttons on the cover page use GoTo actions to jump to "Pricing," "Case Studies," and "Next Steps" sections instantly. The result is a polished document that behaves like a web presentation.
Malicious PDF: Launch Action in the Wild
A phishing campaign distributes a PDF with a disguised Launch action. When opened, the document displays a realistic "verification required" message while the Launch action silently attempts to execute a hidden executable embedded in the PDF. Modern PDF viewers (Adobe Reader, Chrome PDF viewer) block Launch actions and display a security warning. Enterprise IT teams use Group Policy to disable all PDF JavaScript and Launch actions system-wide. This is why PDF/A files — which prohibit all actions — are required for archival storage: an archived PDF with no actions is permanently safe to open.
When PDF Actions Are Essential
Form Calculation
Calculate triggers automatically update totals, subtotals, taxes, and dependent fields when the user enters data — eliminating manual arithmetic and input errors.
Input Validation
Validate triggers enforce data types, ranges, formats (dates, phone numbers, postal codes), and required fields — catching errors before submission, not after.
Document Navigation
GoTo actions on buttons, bookmarks, and table-of-contents links let users jump directly to sections — essential for long documents like technical manuals and contracts.
Form Submission
SubmitForm actions send completed form data to web servers via HTTP — enabling PDF-based data collection workflows without paper printing or manual data entry.
Conditional Visibility
JavaScript actions can show or hide form fields based on other field values — creating conditional form flows that only show relevant sections.
Deep Linking
URI and GoToR actions create hyperlinks to external websites, cross-document references, and specific named destinations — integrating PDFs into broader document ecosystems.
PDF Action Structure in the File
% Field dictionary for a push-button << /Type /Annot /Subtype /Widget /FT /Btn /T (CalculateBtn) /AA % Additional Actions dictionary << /U % MouseUp trigger << /Type /Action /S /JavaScript /JS (var t = this.getField("Total"); t.value = this.getField("Line1").value + this.getField("Line2").value;) >> >> >>
Common Mistakes to Avoid
- Using JavaScript actions in archival PDFs. All actions — including JavaScript, GoTo, and SubmitForm — are prohibited in PDF/A files. If you need an archival PDF, strip all actions before converting to PDF/A. Keep the interactive version separate from the archival copy.
- Relying on Calculate triggers firing in a specific order. The PDF specification does not guarantee the order in which Calculate actions fire across multiple fields. Explicitly set field calculation order in Acrobat (Forms > Edit, calculation order tab) or use a single JavaScript function to calculate all dependent values in sequence.
- Using Launch actions to open attachments. Launch actions that open external files or executables are a serious security risk and are disabled by default in most modern PDF viewers. Use URI actions to open web URLs, or GoTo actions for navigation — never assume Launch will execute.
- Writing JavaScript that uses viewer-specific APIs. PDF JavaScript implementations vary between Adobe Acrobat, Foxit, browser PDF viewers (Chrome/Firefox), and others. What works in Acrobat may fail silently in Chrome. Test JavaScript actions in every viewer your audience may use.
- Not providing a non-JavaScript fallback for critical workflows. If your form requires JavaScript to calculate totals or validate required fields, always provide clear instructions for users whose PDF viewer has JavaScript disabled — or provide a web-based alternative for browsers.
Frequently Asked Questions
Triggers are named events (document open, button MouseUp, field change) that cause PDF actions to execute. Actions are operations: JavaScript execution, GoTo page navigation, URI opening, SubmitForm, ResetForm, and media playback. Every interactive behaviour in a PDF is a trigger-action pair.
OpenAction is an action at the document catalog level that fires automatically when the PDF is opened. Common uses: navigate to a specific page or named destination; initialise form field values via JavaScript; show/hide fields based on conditions. Security-conscious viewers may prompt users before running OpenAction JavaScript.
Form field triggers: MouseUp (most common), MouseDown, MouseEnter, MouseExit, OnFocus, OnBlur, Format, Validate, Calculate, Keystroke. The Calculate trigger is particularly important — it fires automatically when any field value changes and is used for real-time form recalculation.
GoTo navigates within the current PDF (to a page number or named destination) — works offline. URI opens an external URL in the system browser — requires internet. GoToR navigates to a location in a different PDF file. They serve different navigation purposes and should not be confused.
Yes. PDF JavaScript and Launch actions are the primary vectors for PDF-based malware. Modern viewers sandbox JavaScript, prompt before running actions, and disable Launch actions by default. PDF/A files prohibit all actions — making them inherently safer for archiving. Never open unexpected PDF files with JavaScript enabled.
Yes. In Adobe Acrobat/Reader: Preferences > JavaScript — disable Enable Acrobat JavaScript. For Launch: Preferences > Trust Manager. Enterprise IT can enforce via Group Policy. Chrome and Firefox's built-in PDF viewers restrict JavaScript by default. PDF/A format prohibits all actions at the file format level.
Build Interactive PDFs — Free
PDFlyst's PDF Editor gives you the tools to create, edit, and manage PDF forms and interactive documents.
Open PDF Editor — Free