PDF/A and PDF/UA

Use pdfa for archival output and tagged for document structure and PDF/UA validation. The selected standard determines which metadata and attachments are allowed.

import { render } from "takumi-pdf";

const pdf = await render(invoice, {
  pdfa: "3b",
});

Conforming output includes an sRGB output intent and XMP metadata. Fonts are always embedded and subset, with or without PDF/A.

Levels

The u levels add no output cost. Takumi always writes ToUnicode maps.

PDF/A-3 and PDF/A-4f allow arbitrary file attachments. ZUGFeRD and Factur-X electronic invoices expect "3b". See Attachments.

PDF/A-1 is not offered. It prohibits transparency.

Validation runs during rendering. When a document cannot conform, the render fails with the violated rule instead of writing a broken file.

Validate your generated document with veraPDF. Internal checks do not replace reviewing reading order, alternative text, or the meaning of your content.

Tagged output

tagged defaults to true, which writes a structure tree from the document's HTML semantics. This alone does not request PDF/UA validation.

Set tagged: "ua1" to also validate against PDF/UA-1:

import { render } from "takumi-pdf";

const pdf = await render(report, {
  pdfa: "2a",
  tagged: "ua1",
  lang: "en",
  metadata: {
    title: "Annual report",
    creationDate: "2026-08-06",
  },
});

The structure tree comes from the HTML semantics:

Heading levels are normalized in the structure tree. A document starting with h2 gets H1, and a jump from h1 to h4 becomes H1 followed by H2. Use meaningful heading levels in your source even when their visual sizes differ.

Header cells carry a Scope attribute: Column inside thead, Row elsewhere. A scope attribute on the cell overrides it. rowspan and colspan become RowSpan and ColSpan attributes. A table that spans pages stays one Table element. The repeated header band is marked as an artifact.

Table elements follow the rendered layout, like the rest of the tree. A <table> whose display is overridden gets none, and neither does a table built from flex rows. Screen readers cannot navigate those by row or column, and the file still passes PDF/UA, because the validator only checks the tags that are there.

Set tagged: false only when you do not need a structure tree and the selected standard permits it.

PDF/UA-2

tagged: "ua2" validates against PDF/UA-2 instead. The standard is PDF 2.0 only, so it pairs with pdfa: "4", pdfa: "4f", or plain PDF.

import { render } from "takumi-pdf";

const pdf = await render(report, {
  pdfa: "4",
  tagged: "ua2",
  lang: "en",
  metadata: {
    title: "Annual report",
    creationDate: "2026-08-08",
  },
});

Links and outline entries target structure elements, not page positions. Reading order survives when a viewer follows one.

Compatible options

Invalid combinations are TypeScript type errors. PDF/UA-1 uses PDF 1.7. PDF/A-4 and PDF/UA-2 use PDF 2.0. The two generations never mix.

See Attachments.

Validators require inputs the renderer cannot supply:

• lang is the document language. A-levels and PDF/UA require it. PDF/UA-2 fails the render without it. A passage in another language needs its own lang attribute.
• metadata.title is required by PDF/UA.
• metadata.creationDate is required by the a levels. Use UTC "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS". A fixed date keeps output byte-identical across runs.

PDF/UA also requires a document outline. Takumi generates it from headings.