PDF Forms: PDF Template Designer

Forms collect data. But the data rarely stays in the form. It becomes contracts, receipts, applications, reports, confirmations, and compliance documents. Organizations need to transform submission data into formatted PDFs that match their document standards, brand guidelines, or regulatory requirements.

Form.io provides three distinct PDF capabilities that address different parts of this workflow: generating PDFs from any webform submission, designing custom PDF templates that control output formatting, and converting existing PDF documents into interactive web forms with pixel-perfect output. Each capability serves different use cases, and understanding the distinctions helps you choose the right approach.

PDF Generation from Webform Submissions

Every webform submission in Form.io can be downloaded as a PDF. Navigate to any submission in the Developer Portal, click the PDF icon, and the platform generates a formatted document containing the submitted data.

This works without configuration. The PDF reflects the form structure: field labels, submitted values, layout organization. For simple use cases where you need a printable record of what someone submitted, this default behavior requires no setup.

The generation happens server-side through the PDF Server, which renders the submission using a viewer application and converts the result to PDF. You can customize aspects of this rendering through URL parameters:

{{projectUrl}}/form/{{pdfForm}}/submission/{{pdfSubmission}}/download?token={{downloadToken}}

Available parameters include margins, page size, orientation, and Bootstrap theme selection. The PDF documentation covers the complete parameter list.

For programmatic access, the API provides the same capability:

{{projectUrl}}/form/{{pdfForm}}/submission/{{pdfSubmission}}/download?token={{downloadToken}}

This enables your application to generate PDFs on demand, attach them to emails, store them in document management systems, or present them to users for download.

The PDF Template Designer

Default PDF generation outputs all form data in the form’s layout. But a 50-field application form does not need a 50-field PDF receipt. A worker’s compensation claim needs a summary document, not a reproduction of every input. The PDF Template Designer solves this by letting you design a separate layout that controls what appears in the PDF output.

The Template Designer is part of the PDF Plus offering for Enterprise self-hosted deployments. Once enabled, a PDF tab appears in the form header between Data and Actions.

Entering the Template Designer opens a specialized builder. It resembles the standard form builder, but serves a different purpose. Instead of defining what users fill out, you define what the PDF contains. The original webform remains unchanged. Users still see and complete all fields. But the PDF output shows only what you place in the template.

The builder provides two component sources. Layout components (panels, columns, tables) let you organize the PDF structure. The Existing Fields tab lists every component from the webform. Drag fields from Existing Fields into your layout to include their submission data in the PDF output.

This separation is powerful. Consider an insurance application with sections for personal information, employment history, medical background, beneficiary details, and signatures. The webform needs all of it. But the confirmation receipt might show only name, policy type, effective date, and signature. The PDF Template Designer lets you build exactly that output without affecting the data collection form.

Use Cases for Custom Templates

The Template Designer supports document types that require specific formatting:

Receipts and Confirmations extract key fields from longer forms. A customer submits a 30-field order form; the receipt shows order number, items, total, and payment confirmation.

Contracts and Agreements combine submitted data with standard legal text. The webform collects party names, terms, and signatures. The PDF template arranges these into a properly formatted contract document.

Reports and Summaries transform detailed submissions into executive-friendly formats. A comprehensive assessment form generates a one-page summary highlighting key findings.

Mailers and Communications format submission data for printing and mailing. Address blocks, response forms, and personalized content all derive from submission data but appear in mail-ready layouts.

PDF-First Forms: Converting Existing PDFs

Many organizations have existing PDF forms: government applications, insurance claims, standardized industry documents. Users expect to see these familiar formats. Recreating them as webforms loses the visual continuity that users rely on.

PDF-First forms address this by letting you upload an existing PDF and overlay interactive Form.io components directly on top of it. Users see the original PDF background with fields positioned exactly where the paper form expects them. When they submit, the data saves to MongoDB (or compatible) like any Form.io submission. When they download or print, the output renders onto the original PDF with pixel-perfect positioning.

To create a PDF-First form, select “PDF Form” when creating a new form, then upload your PDF document. After processing, the PDF opens in the form builder where you drag overlay components onto specific positions.

The available overlay components include text fields, text areas, checkboxes, radio buttons, select dropdowns, date/time pickers, and signatures. These components behave similarly to their webform counterparts but include PDF-specific settings for positioning and sizing. The vertical size of text components controls font size in the rendered PDF.

PDF-First forms participate in all standard Form.io features: staging and versioning, team workflows, conditional logic, and integrations. The PDF background travels with the form definition when you migrate between environments.

Auto-Conversion of Fillable PDFs

If your existing PDF already contains form fields with standard metadata (common in PDFs created with Adobe Acrobat’s form tools), Form.io can automatically convert those fields to Form.io components. Upload the PDF, and the platform reads the field definitions and creates corresponding overlay components in the correct positions.

This works for PDFs with embedded XFA or AcroForm data. The conversion maps PDF field types to Form.io component types, preserving labels and positions. You can then modify the generated components, add validation rules, or connect them to other Form.io features.

For PDFs without metadata (scanned documents or flat PDFs), the PDF Server Plus offering integrates with AWS Textract to detect field positions automatically. Textract analyzes the document image, identifies where fields should be, and generates Form.io components at those locations. This requires additional AWS configuration but enables modernization of legacy paper forms.

Hybrid Approach: Webform Input, PDF Output

Some organizations want the user experience benefits of responsive webforms while maintaining pixel-perfect PDF output. Form.io supports this hybrid approach.

Create a PDF-First form by uploading your PDF and positioning overlay components. Then change the Display setting from “PDF” to “Webform” or “Wizard.” Users now see a standard responsive form when completing the submission. But because the PDF background remains attached, the PDF generation process still uses the original PDF as the output template.

This gives you both worlds: users fill out a mobile-friendly, responsive webform. The downloaded PDF shows their data on the official document background exactly as it would appear on paper.

Custom Viewer Applications

The default PDF generation uses a hosted viewer application to render submissions before conversion. For specialized requirements, you can create custom viewers.

Fork the default Form Viewer, modify it to match your requirements (different CSS frameworks, custom headers, corporate branding), compile it, and host it on your own infrastructure. Then configure your forms to use your custom viewer through form settings or environment variables.

This approach supports use cases like:

  • Corporate branded PDF output with logos and standard styling
  • Different viewer configurations for different form types
  • Custom elements injected into the PDF that do not come from submission data
  • Integration with existing document generation pipelines

The FORMIO_VIEWER environment variable on the PDF Server sets the default viewer for all generated PDFs. Individual forms can override this through custom properties.

Page Breaks and Layout Control

For long submissions, controlling where page breaks occur in the PDF output matters. Form.io supports CSS-based page break control through custom classes.

Add the class page-break-before to any component that should start on a new page. When the PDF renders, it inserts a page break before that element. This works for panels, field sets, or any component that accepts custom CSS classes.

{
  "type": "panel",
  "title": "Section Two",
  "customClass": "page-break-before",
  "components": [...]
}

The PDF Settings in form configuration provide additional layout controls: hiding the form title, rendering in condensed mode with minimal padding, showing plain text without field borders, and setting global font sizes.

API Integration for PDF Generation

Applications can generate PDFs programmatically through the submission download endpoint. The typical flow:

  1. Generate a temporary token scoped to the specific submission
  2. Use the token to request the PDF download
  3. Receive the PDF binary for storage, email attachment, or user download
// First, get a temporary token
const tokenResponse = await fetch(`${baseUrl}/token`, {
  method: 'GET',
  headers: {
    'x-jwt-token': userToken,
    'x-allow': `GET:/project/${projectId}/form/${formId}/submission/${submissionId}`
  }
});

// Then download the PDF
const pdfResponse = await fetch(
  `${baseUrl}/${formPath}/submission/${submissionId}/download?token=${tempToken}`
);

The API documentation covers authentication patterns and available parameters.

When to Use Each PDF Capability

Use default PDF generation when you need printable submission records without specific formatting requirements. No configuration needed; every submission can download as PDF immediately.

Use the PDF Template Designer when your PDF output needs different content or layout than your webform. Receipts, summaries, and contracts typically need custom templates.

Use PDF-First forms when users expect to see a specific document format, when you are modernizing existing paper workflows, or when regulatory requirements mandate specific document layouts.

Use the hybrid approach when you want responsive webform UX but must produce output on official document backgrounds.

Limitations and Considerations

PDF Server resources matter. Large forms and complex PDFs require processing time and memory. The PDF Server documentation recommends 2 CPU cores and 4GB RAM as a minimum. Very large documents may need timeout adjustments.

Page size must be standard. PDF uploads require standard page sizes like A4 or Letter. Non-standard sizes produce errors. Re-save documents with standard dimensions before uploading.

ARM64 is not supported. The PDF Server currently does not support Apple M1 chips or ARM64 architecture. Deploy on Intel-based systems or x86 containers.

Template Designer requires PDF Plus. The custom template capability is part of the PDF Plus Enterprise offering, not the basic PDF generation.

Related Resources