Total: $1,290
`);
```
Headers, footers, and `measure()` accept the same inputs.
## Page setup [#page-setup]
```tsx twoslash
import type { ReactNode } from "react";
declare const report: ReactNode;
// ---cut---
import { render } from "takumi-pdf";
const pdf = await render(report, {
// [!code highlight:3]
size: "letter", // a page keyword, or { width, height } in CSS px at 96 dpi
landscape: true,
margin: { top: 48, right: 32, bottom: 48, left: 32 },
});
```
| Option | Type | Default | Description |
| ----------------- | --------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------- |
| `size` | a page keyword or `{ width, height }` | `"a4"` | Page size in CSS px at 96 dpi. Keywords ignore case. |
| `landscape` | `boolean` | `false` | Swaps page width and height, including explicit sizes. |
| `margin` | `number`, `"auto"`, or `{ top?, right?, bottom?, left? }` | `"auto"` | `"auto"` fits the band on that side, and a side left out of the object is `"auto"` too. |
| `backgroundColor` | CSS color | unset | Fills the page box, margins included, under everything. |
`size` accepts these paper sizes. Each keyword uses portrait orientation:
| Keyword | Size | Keyword | Size |
| ------- | ------------ | ---------- | ------------ |
| `"a3"` | 297 × 420 mm | `"jis-b4"` | 257 × 364 mm |
| `"a4"` | 210 × 297 mm | `"jis-b5"` | 182 × 257 mm |
| `"a5"` | 148 × 210 mm | `"ledger"` | 11 × 17 in |
| `"b4"` | 250 × 353 mm | `"legal"` | 8.5 × 14 in |
| `"b5"` | 176 × 250 mm | `"letter"` | 8.5 × 11 in |
Set `landscape` to turn any of them, or pass `{ width, height }` for a size with no keyword.
Set page geometry through these options. CSS `@page` rules are not parsed.
Automatic top and bottom margins fit the header or footer, including its 20px inset from the paper edge. They are at least 37.8px on ordinary page sizes. Without a header or footer, the default is 37.8px (1cm). See [Headers and footers](/docs/pdf/headers-and-footers#sizing-the-margin).
Leave `backgroundColor` unset for white paper.
A viewer draws white by default, and the file stays free of a full-page rectangle.
## Reuse a renderer [#reuse-a-renderer]
`render()` reuses a shared renderer. Create a `PdfRenderer` when you need a separate font registry:
```tsx twoslash
import type { ReactNode } from "react";
declare const doc: ReactNode;
// ---cut---
import { PdfRenderer } from "takumi-pdf";
// [!code highlight:2]
const renderer = new PdfRenderer();
await renderer.registerFont("https://example.com/fonts/Inter-Regular.woff2");
const pdf = await renderer.render(doc);
```
Registered fonts are deduplicated across calls. Replace the example URL with your font file.
## Runtimes [#runtimes]
Use the default import on Node.js, Bun, and Cloudflare Workers. For manual initialization, import `takumi-pdf/no-init`.
### Next.js [#nextjs]
Import `takumi-pdf/next` in a Next.js route handler. This entry supports the Node and Edge runtimes without a `serverExternalPackages` entry.
```ts
import { render } from "takumi-pdf/next";
```
### In the browser [#in-the-browser]
For browser bundles, initialize the renderer with `takumi-pdf/no-init` and `takumi-pdf/wasm-url`:
```ts
import init, { render } from "takumi-pdf/no-init";
import wasmUrl from "takumi-pdf/wasm-url";
await init({ module_or_path: wasmUrl });
```
`takumi-pdf/wasm-url` resolves the binary with `new URL(specifier, import.meta.url)`.
Vite, webpack, and Turbopack rewrite that call to the asset they emit.
The module has no top-level `await`, so it also works in a worker bundled as an IIFE.
Server code should keep the default entry. A Vite SSR build leaves the URL pointing at the
server chunk, where the asset never lands.
On Turbopack, drop any `turbopack.rules` entry mapping `*.wasm` to `type: "wasm"`.
That rule makes Turbopack instantiate the binary and look for wasm-bindgen glue the
package does not ship.
## Choose the next guide [#choose-the-next-guide]
| Task | Guide |
| ---------------------------------------------- | ----------------------------------------------------------- |
| Control page breaks and repeated table headers | [Pagination](/docs/pdf/pagination) |
| Add page numbers | [Headers and footers](/docs/pdf/headers-and-footers) |
| Load fonts, logos, and photos | [Fonts and images](/docs/pdf/fonts-and-images) |
| Add links or a table of contents | [Links, outline, and metadata](/docs/pdf/links-and-outline) |
| Create a receipt or label | [Single-page viewport](/docs/pdf/single-page) |
| Generate archival or accessible output | [PDF/A and PDF/UA](/docs/pdf/pdf-a) |
For complete document patterns, see [Invoices](/docs/pdf/invoices), [Reports](/docs/pdf/reports), and [Charts](/docs/pdf/charts).
# Invoices (/docs/pdf/invoices)
Render line items and totals as a paged document. If your invoice format requires embedded XML, add it as an attachment with the required PDF/A and XMP settings.
## A plain invoice [#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:
```tsx twoslash
import type { ReactNode } from "react";
declare const invoice: { number: string };
declare function InvoiceDocument(props: { data: typeof invoice }): ReactNode;
// ---cut---
import { googleFonts } from "@takumi-rs/helpers";
import { measure, render } from "takumi-pdf";
import { PageNumber, TotalPages } from "takumi-pdf/primitives";
const footer = (
Invoice {invoice.number}
Page
);
const fonts = await googleFonts(["Inter"]);
// [!code highlight]
const { height } = await measure(footer, { size: "a4", fonts });
const pdf = await render(
{item.description}
{item.amount}
;
```
Apply the same style to the totals block.
## Electronic invoices [#electronic-invoices]
Factur-X and ZUGFeRD combine a readable PDF invoice with structured XML. Configure the container for the profile you are implementing:
| The standard requires | The option |
| ---------------------------- | ------------------ |
| A PDF/A-3 container | `pdfa: "3b"` |
| The XML attached by name | `attachments` |
| An `fx:` XMP block | `metadata.xmp` |
| A modification date per file | `modificationDate` |
| Embedded subset fonts | always on |
Each attachment's `modificationDate` falls back to `metadata.creationDate`. Setting the document date once covers both.
```tsx twoslash
import type { ReactNode } from "react";
import type { XmpSchema } from "takumi-pdf";
declare const invoice: ReactNode;
declare const xml: string;
declare const facturXmp: XmpSchema;
// ---cut---
import { render } from "takumi-pdf";
const pdf = await render(invoice, {
lang: "en",
// [!code highlight:2]
pdfa: "3b",
tagged: "ua1",
metadata: {
title: "Invoice INV-2026-0042",
creationDate: "2026-08-06",
// [!code highlight]
xmp: [facturXmp],
},
attachments: [
{
name: "factur-x.xml",
data: xml,
mimeType: "text/xml",
description: "Factur-X 1.0 MINIMUM invoice data",
relationship: "data",
},
],
});
```
The renderer checks PDF conformance while writing. It does not validate invoice XML, tax rules, or acceptance by a receiving system.
Takumi does not build the invoice XML. Use a library for the profile, or emit the elements the profile lists. The [e-invoice example](https://github.com/kane50613/takumi/tree/master/example/e-invoice) writes a MINIMUM profile by hand.
### Validating the result [#validating-the-result]
Two validators cover the two halves. Both need Java.
[veraPDF](https://verapdf.org) checks the container:
```bash
verapdf --flavour 3b --format text invoice.pdf
verapdf --flavour ua1 --format text invoice.pdf
```
[Mustang](https://www.mustangproject.org) checks the Factur-X half, both the XML and the packaging:
```bash
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 [#accessible-invoices]
For PDF/UA-1 output, set `tagged: "ua1"` and supply the required metadata. Review the reading order and table semantics as well. See [PDF/A and PDF/UA](/docs/pdf/pdf-a).
## Reproducible bytes [#reproducible-bytes]
Use a fixed `metadata.creationDate` with the same content, resources, and renderer version when you need reproducible bytes. A new date changes the file even if the invoice looks the same.
# Links, outline & metadata (/docs/pdf/links-and-outline)
Add links with ``, bookmarks with `outline`, and document properties with `metadata`.
## Hyperlinks [#hyperlinks]
Anchors with an `href` become clickable link annotations. They appear on every page that their box touches:
```tsx twoslash
import { render } from "takumi-pdf";
const pdf = await render(
{/* [!code highlight] */} Pay online at example.com/pay/1042.
, ); ``` Inline anchors annotate each text run. A link that wraps across lines stays clickable on both lines. Block-level anchors annotate their entire box. `http`, `https`, `mailto` and `tel` links open outside the document. An `href` starting with `#` points inside it instead, to the element carrying that `id`: ```tsx twoslash import { render } from "takumi-pdf"; const pdf = await render(
{/* [!code highlight:2] */}
Jump to the appendix
,
);
```
Internal links jump to the target element. Unresolved fragments and unsupported URL schemes are omitted.
## Table of contents [#table-of-contents]
`Appendix
| Name | Qty |
|---|
DRAFT
Long content that continues on the next page.
| Item | Amount |
|---|---|
| {row.label} | {row.amount} |
Certificate
, {
// [!code highlight]
viewport: { width: 1123, height: 794 }, // A4 landscape in px
});
```
## Content-sized pages [#content-sized-pages]
Omit `height` for a page that grows to fit its content, such as a thermal receipt. Use content or explicit lengths to determine element heights. Percentage heights do not resolve in this mode:
```tsx twoslash
import type { ReactNode } from "react";
declare const receipt: ReactNode;
// ---cut---
import { render } from "takumi-pdf";
// [!code highlight]
const pdf = await render(receipt, { viewport: { width: 302 } }); // 80mm at 96 dpi
```
`viewport` cannot be combined with `size`, `landscape`, `margin`, `header`, `footer`, or `pageRanges`. Use padding inside the document for whitespace around a single page. Hyperlinks, `outline`, and `metadata` work in both modes.
# Tickets & receipts (/docs/pdf/tickets)
Use `viewport` for a ticket, shipping label, certificate, or receipt. Set both dimensions for fixed paper, or omit the height for a receipt that grows with its content.
## Labels and tickets [#labels-and-tickets]
Give `viewport` the paper size in CSS px at 96 dpi. Percentage heights resolve against it, so a full-bleed background is `height: "100%"`:
```tsx twoslash
declare const qrSvg: Uint8Array;
// ---cut---
import { render } from "takumi-pdf";
// 4in × 6in shipping label
const pdf = await render(
ACME · Priority
1Z 999 AA1 0123 4567
,
// [!code highlight]
{ viewport: { width: 384, height: 576 }, images: [{ src: "qr.svg", data: qrSvg }] },
);
```
Generate the QR code or barcode as SVG and pass its bytes through `images`. Vector paths scale with the page. Check that the printed code has enough physical size and clear space for scanning.
Common sizes in CSS px:
| Paper | Width × height |
| --------------- | -------------- |
| A4 portrait | 794 × 1123 |
| A4 landscape | 1123 × 794 |
| A6 postcard | 397 × 559 |
| 4in × 6in label | 384 × 576 |
| 80mm receipt | 302 × auto |
## Receipts [#receipts]
Omit `height` and the page grows to fit the content. A till receipt is one continuous strip, however many lines it has:
```tsx twoslash
import type { ReactNode } from "react";
declare const receipt: ReactNode;
// ---cut---
import { render } from "takumi-pdf";
// [!code highlight]
const pdf = await render(receipt, { viewport: { width: 302 } }); // 80mm at 96 dpi
```
Percentage heights do not resolve in this mode. Nothing knows the final height until the layout finishes.
## Certificates [#certificates]
A certificate is a fixed page with artwork behind the text. Gradients, borders, radii, and transforms all draw as vectors:
```tsx twoslash
declare const recipient: string;
// ---cut---
import { render } from "takumi-pdf";
const pdf = await render(
1Z 999 AA1 0123 4567
CERTIFICATE OF COMPLETION
{recipient}
,
{ viewport: { width: 1123, height: 794 } },
);
```
Overflowing content is clipped, exactly like an image render. Size the text to the box, or measure it first.
## Options and overflow [#options-and-overflow]
`viewport` rejects the paged options as type errors. Everything else carries over, including `pdfa` and `attachments`. See [Single-page viewport](/docs/pdf/single-page).
The same component can also render as a PNG with `takumi-js`. Pass image dimensions to the image renderer instead of PDF page options.
# Performance & Optimization (/docs/performance-and-optimization)
## Reuse the renderer [#reuse-the-renderer]
```tsx twoslash
import { render } from "takumi-js";
const image = await render(Hello Takumi
, {
width: 1200,
height: 630,
});
```
`render` and `ImageResponse` reuse a managed renderer. No cache setup is needed. When using `Renderer` directly, create it outside the request handler so registered fonts and decoded resources survive between renders.
## Know what is cached [#know-what-is-cached]
| Work | Lifetime | Configuration |
| :---------------------------------------------- | :-------------------- | :----------------------------------------------------------------- |
| Decoded images, SVG rasters, parsed stylesheets | Renderer | `cacheMaxBytes`, 16 MiB by default |
| Glyph outlines and rasterized masks | Loaded backend module | `setGlyphCacheMaxBytes`, 8 MiB by default |
| Parsed Tailwind classes | Loaded backend module | Automatic, bounded internally |
| Resolved Tailwind declarations | Render | Automatic, separated by viewport width, font size, and pixel ratio |
| Google Fonts CSS | Fetch implementation | Automatic, bounded internally |
| Downloaded image bytes | Caller-provided cache | Optional `images.fetchCache` |
Cache budgets account for retained entries, not total process memory. Fonts, active renders, output buffers, and allocator overhead use memory too. See [image caching](/docs/load-images#decode-caching) and [Google Fonts](/docs/typography-and-fonts#from-google-fonts) for resource-specific behavior.
## Measure cold and repeated renders [#measure-cold-and-repeated-renders]
Measure the first render separately from repeated renders. Font downloads and decoding affect startup; layout, painting, and encoding still happen on a warm renderer.
Use representative text, images, output formats, and concurrent requests. Compare latency and memory before changing a budget. Increasing a cache helps only when it keeps work that later renders reuse.
### Resource cache [#resource-cache]
```ts twoslash
import { Renderer } from "takumi-js/node";
const renderer = new Renderer({ cacheMaxBytes: 64 * 1024 * 1024 });
```
Raise the budget when frequently reused images or stylesheets are being evicted. For images used only once, [`cache: "none"`](/docs/load-images#decode-caching) avoids displacing reusable entries. An unbounded `images.fetchCache` is separate from this budget.
### Glyph cache [#glyph-cache]
```ts twoslash
import { setGlyphCacheMaxBytes } from "takumi-js";
setGlyphCacheMaxBytes(64 * 1024 * 1024);
```
Call this before the first render. Outlines and masks share the budget across renderers in the same backend module. Large glyph sets or text sizes can benefit from more space, but benchmark your content first.
## Keep network requests out of repeated work [#keep-network-requests-out-of-repeated-work]
Bundle fonts for predictable startup without a font service. WOFF2 saves transfer and storage space but needs decompression; TTF avoids that step. A reused renderer decodes a registered file once. See [local fonts and CI](/docs/typography-and-fonts#fonts-in-ci-and-offline-renders).
For repeated remote images, use a bounded [fetch cache](/docs/load-images#external-images). The renderer's decode cache does not replace a download cache.
## Reduce painting work [#reduce-painting-work]
Each filtered node needs an offscreen layer. Put filters on one node when they should apply to the same composed content. Moving filters from children to a parent can change the output, so compare the result.
On servers, the native backend supports multithreaded rendering. The Wasm backend is single-threaded. `takumi-js` selects the backend for the environment; use explicit backend imports only when you need to control that choice.
# Reference (/docs/reference)
## Node Types [#node-types]
Every node is a `container`, `text`, or `image`. A node tree holds content and style only. Fonts, images, and output options are separate arguments to `render`, so a tree stays plain JSON and can come straight out of a structured-output schema.
All nodes accept these fields:
Hello Tailwind!
,
{
width: 1200,
height: 630,
// [!code ++]
css: stylesheet,
},
);
}
```
```tsx title="vite.config.ts"
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";
export default defineConfig({
// [!code ++]
plugins: [tailwindcss()],
});
```
## Tailwind without a build step [#tailwind-without-a-build-step]
The `tw` prop runs a built-in parser with no build step. It matches [the satori prop](https://github.com/vercel/satori#tailwind-css), so `next/og` code ports as-is.
```tsx twoslash
import { render } from "takumi-js";
const image = await render(
// [!code highlight:3]
Hello Tailwind!
{isError ? "Something went wrong" : "Success!"}
;
```
### Preflight [#preflight]
The native parser applies no Tailwind Preflight by default, so elements keep their UA margins. A `