PDF/A and PDF/UA

pdfa selects a PDF/A archival level. tagged controls the structure tree and PDF/UA accessibility validation. The level you pick decides which other options are allowed.

import { render } from "takumi-pdf";

const pdf = await render(invoice, {
  pdfa: "3b",
  metadata: { title: "Invoice 1042", creationDate: "2026-08-06" },
});

Conforming output carries an sRGB output intent and XMP metadata. Fonts are embedded and subset with or without pdfa.

LevelsCopy Anchor Link

• The u levels cost nothing extra. Takumi always writes Unicode mappings for text.
• PDF/A-3 and PDF/A-4f allow file attachments. ZUGFeRD and Factur-X electronic invoices expect "3b". See Attachments.
• PDF/A-1 is not offered, because it prohibits transparency.

ValidationCopy Anchor Link

The renderer validates the file while writing it. If the document cannot conform, the render fails and names the violated rule.

CI renders test documents at every pdfa level and both PDF/UA levels, then checks each one with veraPDF. Run veraPDF on your own documents as well:

verapdf --flavour 3b --format text invoice.pdf
verapdf --flavour ua1 --format text invoice.pdf

Neither check reviews reading order, alternative text quality, or the meaning of your content.

Required inputsCopy Anchor Link

Validators require some inputs the renderer cannot infer:

A missing input fails the render. A few more rules:

• Write creationDate as UTC "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS". A fixed date keeps the output byte-identical across runs.
• Mark a decorative image with alt="".
• Give a passage in another language its own lang attribute.
• PDF/UA requires a document outline. tagged: "ua1" and "ua2" build it from headings, even without outline: true.

Tagged outputCopy Anchor Link

tagged defaults to true, which writes a structure tree from the document's HTML semantics. It does not validate against PDF/UA on its own.

Set tagged: "ua1" to 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 maps HTML elements like this:

A figure takes its description from the first img inside it with non-empty alt. Without one, it gets no Figure element.

HeadingsCopy Anchor Link

Heading levels are normalized in the structure tree. A document that starts 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.

TablesCopy Anchor Link

• Header cells carry a Scope. It is Column inside thead and 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, and the repeated header is marked as an artifact.

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

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

PDF/UA-2Copy Anchor Link

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

import { render } from "takumi-pdf";

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

Under PDF/UA-2, links and outline entries target structure elements, not page positions. A viewer that follows one keeps the reading order.

Compatible optionsCopy Anchor Link

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

uncoveredText: "placeholder" fails with any pdfa level and both PDF/UA levels. See Uncovered text.