Invoices

An invoice PDF serves two readers. A person reads the layout. A tax authority's software reads structured data attached inside the same file. takumi-pdf writes both halves.

A plain invoice

Line items flow across pages. A footer carries the page counter. measure returns the band's height, so the bottom margin always clears it:

import { googleFonts } from "@takumi-rs/helpers";
import { measure, render } from "takumi-pdf";

const footer = (
  <div tw="flex w-full justify-between px-12 text-[10px] text-[#6b7280]">
    <span>Invoice {invoice.number}</span>
    <span tw="flex">
      Page <span className="pageNumber" /> of <span className="totalPages" />
    </span>
  </div>
);

const fonts = await googleFonts(["Inter"]);
const { height } = await measure(footer, { size: "a4", fonts });

const pdf = await render(<InvoiceDocument data={invoice} />, {
  size: "a4",
  margin: { top: 48, bottom: height + 32, left: 48, right: 48 },
  footer,
  fonts,
});

Mark each line row break-inside: avoid so a row never straddles a page. The Tailwind class is break-inside-avoid:

import "takumi-pdf";

<div tw="flex break-inside-avoid gap-3 pt-3 text-xs">
  <span tw="flex-1">{item.description}</span>
  <span tw="w-[100px] text-right">{item.amount}</span>
</div>;

Wrap the totals block the same way. It is the part a reader most expects to see whole.

Electronic invoices

Factur-X and ZUGFeRD are the same file twice: a readable invoice, plus the invoice as XML attached inside it. The standards pin how that file is packaged.

Each attachment's modificationDate falls back to metadata.creationDate. Setting the document date once covers both.

import { render } from "takumi-pdf";

const pdf = await render(invoice, {
  lang: "en",
  pdfa: "3b",
  tagged: "ua1",
  metadata: {
    title: "Invoice INV-2026-0042",
    creationDate: "2026-08-06",
    xmp: [facturXmp],
  },
  attachments: [
    {
      name: "factur-x.xml",
      data: xml,
      mimeType: "text/xml",
      description: "Factur-X 1.0 MINIMUM invoice data",
      relationship: "data",
    },
  ],
});

The renderer validates while it writes. A document that cannot conform fails with the violated rule, instead of producing a file a tax portal rejects.

Takumi does not build the invoice XML. Use a library for the profile, or emit the elements the profile lists. The e-invoice example writes a MINIMUM profile by hand.

Validating the result

Two validators cover the two halves. Both need Java.

veraPDF checks the container:

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

Mustang checks the Factur-X half, both the XML and the packaging:

java -jar Mustang-CLI.jar --action validate --source invoice.pdf

Mustang finds the profile through the fx: XMP block. Takumi writes the values and the schema description PDF/A demands, so the two cannot drift. It does not check the values: a wrong profile name surfaces in Mustang, not at render time.

Accessible invoices

Public-sector buyers often require an accessible invoice. tagged: "ua1" validates the structure tree against PDF/UA-1 during the render. See PDF/A for what it needs.

Reproducible bytes

A fixed metadata.creationDate makes the output byte-identical across runs. The same invoice hashes to the same value, which suits archival storage and golden tests.