@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. |

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. |

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.