Links, outline & metadata

Add links with <a href>, bookmarks with outline, and document properties with metadata.

HyperlinksCopy Anchor Link

An <a> with an href becomes a clickable link on every page its box touches:

import { render } from "takumi-pdf";

const pdf = await render(
  <p>
    Pay online at <a href="https://example.com/pay/1042">example.com/pay/1042</a>.
  </p>,
);

An inline link is clickable on each line it wraps across. A block-level link covers its whole box.

http, https, mailto, and tel links open outside the document. An href that starts with # jumps to the element with that id:

import { render } from "takumi-pdf";

const pdf = await render(
  <div>
    <a href="#appendix">Jump to the appendix</a>
    <h1 id="appendix">Appendix</h1>
  </div>,
);

A link to a missing id or with another URL scheme gets no annotation.

Table of contentsCopy Anchor Link

<TargetPageNumber /> prints the page number of an internal link's target. Put it inside an <a href="#id">, or pass href so it renders its own link. In HTML input, put an element with the targetPageNumber class inside the link.

import { render } from "takumi-pdf";
import { TargetPageNumber } from "takumi-pdf/primitives";

const pdf = await render(
  <div>
    <a href="#results" tw="flex items-baseline gap-2">
      <span>Results</span>
      <span tw="flex-1 border-b border-dotted border-gray-400" />
      <TargetPageNumber tw="w-8 shrink-0 text-right" />
    </a>
    <h1 id="results" style={{ breakBefore: "page" }}>
      Results
    </h1>
  </div>,
);

The stretched span draws the dot leader. format takes any counter style, so format="upper-roman" prints IV for page 4.

A fragment that names no element prints nothing, the same rule links follow.

Reserve space for page numbersCopy Anchor Link

A page number exists only after pagination. Takumi paginates, fills the numbers in, and lays the document out again. A number that widens its line can move a page break, and the moved break can renumber the entry. The render repeats this up to three times, then keeps the last result.

The example reserves width with w-8 shrink-0 text-right, so a number cannot change the entry's width. Widen it if your document needs more digits.

Headers and footers are laid out per page, outside this loop. A <TargetPageNumber /> in a band renders nothing.

OutlineCopy Anchor Link

Set outline: true to build PDF bookmarks from h1–h6. A deeper heading nests under the shallower heading before it. tagged: "ua1" and "ua2" turn the outline on, since PDF/UA requires one:

import { render } from "takumi-pdf";

const pdf = await render(report, { outline: true });

Clicking a bookmark jumps to the page and position of its heading.

Document metadataCopy Anchor Link

metadata fills the PDF document properties. lang also sets the document language:

import { render } from "takumi-pdf";

const pdf = await render(report, {
  lang: "en",
  metadata: {
    title: "Annual report 2026",
    description: "Consolidated results for fiscal year 2026",
    authors: ["Acme Inc."],
    keywords: ["annual report", "2026"],
    creator: "acme-reporting",
  },
});

Every field is optional for plain PDF output. PDF/A and PDF/UA require some of them. Set a fixed creationDate for reproducible output.