@ogcio/pdf-export

PDF export utilities for form submissions.

npm install @ogcio/pdf-export [email protected]

react is also required if you use the React hook (@ogcio/pdf-export/react).

Entrypoints

| Entrypoint | Description | | ------------------------- | ---------------------------------------------------------------------------------------------- | | @ogcio/pdf-export | Core API (downloadPdf, generatePdf, transformers). No React dependency. | | @ogcio/pdf-export/react | React hook (useDownloadPdf) plus everything from the core entrypoint. Marked 'use client'. |

Fonts

This package bundles the Lato font family (regular and bold). Font files are lazy-loaded via dynamic import and only fetched when the first PDF is generated.

There is no support for loading custom fonts through this package.

Options reference

PdfOptions (passed to downloadPdf / generatePdf / download)

| Option | Type | Default | Description | | ------------ | --------- | -------------- | -------------------------------------------------------------------------------------------------------- | | showTime | boolean | true | When true, the "Time submitted" field shows both date and time. When false, shows date only. | | filename | string | Auto-generated | Custom filename for the downloaded PDF. Auto-generated from title and submission ID if omitted. | | styling | object | — | Advanced layout overrides (page size, margins, colours, font sizes). See PdfStylingSchema for details. | | truncation | object | — | Override display truncation limits for field labels and values. See truncation limits below. |

Truncation limits

Text is truncated before rendering to keep PDFs readable. There are two layers:

• Zod schema (input gate): hard ceiling — inputs exceeding this are rejected outright
• Display truncation (default): what actually renders in the PDF; configurable via truncation

| Field | Zod limit | Display default | Configurable | | ------------ | --------- | -------------------------------- | -------------------------------------------- | | Field labels | 10,000 | 5,000 graphemes | Yes | | Field values | 200,000 | 100,000 graphemes (~40 A4 pages) | Yes | | Title | 1,000 | 200 graphemes | No — matches the 200-character DB constraint |

await downloadPdf(pdfData, {
  truncation: {
    labelLength: 10_000, // max 10_000
    valueLength: 150_000, // max 200_000
  },
})

Truncated text is appended with …. Values above the Zod limit are rejected at runtime with a validation error.

Transformer options (V1Options / V2Options, passed to transformV1ToPdfData / transformV2ToPdfData)

| Option | Type | Default | Description | | --------------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | excludeAttachments | boolean | false | When true, attachment fields are omitted from the PDF output. | | includeFieldNumbers | boolean | true | When true, field labels are prefixed with sequential numbers. | | includeSections | boolean | true | When true, section headers are included in the PDF output. | | includeStatements | boolean | false | When true, statement fields are included and section descriptions are shown. When false, statements are excluded and section descriptions are hidden. | | virusScanMessages | object | Built-in | Map of scan status codes to display messages for attachment fields. Defaults to VIRUS_SCAN_STATUS_EMAIL_MESSAGES from @formsg/shared. |

Form Logic & Visibility

The transformers (transformV1ToPdfData and transformV2ToPdfData) automatically handle field visibility based on form logic if formLogics is provided in the input object.

• Field Filtering: If a field is hidden by logic (e.g., a "Show" rule whose conditions are not met), it will be omitted from the PDF.
• Section Filtering: If all fields within a section are hidden or unanswered, the section header itself will be automatically removed to keep the PDF clean.
• Manual Visibility: The transformers also respect the isVisible property on individual fields/responses if present.

To enable this, ensure your input object includes the formLogics array:

const pdfData = transformV2ToPdfData({
  // ... other input fields
  formFields: form.form_fields,
  formLogics: form.form_logics, // Enables automatic visibility filtering
  content: submission.content,
})

Usage

The examples below use @ogcio/pdf-export — use workspace:* in monorepo consumers.

SSR apps (client-only)

This package is intended for browser/client usage.

• Import only inside files marked with 'use client'
• Do not import from Server Components, route handlers, or server actions

React hook

'use client'

import { useDownloadPdf, transformV1ToPdfData } from '@ogcio/pdf-export/react'

export function DownloadButton({ data }) {
  const { download, isGenerating } = useDownloadPdf({
    onError: (err) => console.error(err),
    onSuccess: () => console.log('Done'),
  })

  const onClick = async () => {
    const pdfData = transformV1ToPdfData(data, {
      excludeAttachments: true,
    })

    await download(pdfData, {
      showTime: false,
    })
  }

  return (
    <button onClick={onClick} disabled={isGenerating}>
      Download PDF
    </button>
  )
}

Direct (non-React) usage

import { downloadPdf, transformV2ToPdfData } from '@ogcio/pdf-export'

const pdfData = transformV2ToPdfData(input, {
  excludeAttachments: true,
  includeStatements: false,
})

await downloadPdf(pdfData, {
  showTime: true,
  filename: 'submission.pdf',
})

Lazy loading

All heavy assets are lazy-loaded via dynamic import() on first use:

• pdfmake library — loaded when generatePdf / downloadPdf is first called
• Lato font files — loaded on first PDF generation

The pdfmake instance is cached after first initialisation, so subsequent calls are fast. Font assets are also cached once loaded.

For the lightest initial page load, trigger PDF generation on user action (e.g. button click) rather than on render.

Security notes

This package includes built-in safeguards:

• Input validation via Zod schemas
• Text sanitisation (control characters removed)
• Filename sanitisation before download
• Size/length limits on key input fields

Consumers should still treat transformer input as untrusted data.