DRAFT
Long content that continues on the next page.
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` takes the page keywords CSS Paged Media defines, portrait as that module writes them:
| 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.
These options are the structured form of `@page`, which takumi does not parse as CSS.
`size` and `margin` map to the descriptors of the same name, `header` and `footer` to its margin boxes.
A margin left at `"auto"` takes the space its band needs: the band's measured
height plus the 20px it is inset from the paper edge, and never less than the
37.8px a page starts with. Without a band on that side it stays at 37.8px, the
1cm Chromium prints at.
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()` keeps one shared renderer alive. Construct `PdfRenderer` directly for applications that manage several font sets:
```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/Inter-Regular.woff2");
const pdf = await renderer.render(doc);
```
Registered fonts deduplicate across calls. Rendering many documents pays the font cost once.
## Runtimes [#runtimes]
`takumi-pdf` ships as WebAssembly. It runs on Node.js, Bun, and Cloudflare Workers.
The module fits the Workers free-tier size limit.
Import `takumi-pdf/no-init` to instantiate the wasm yourself.
### Next.js [#nextjs]
Import `takumi-pdf/next` from a route handler. It hands the binary to Turbopack in the form
Turbopack emits, on the Node runtime and the Edge runtime alike, so the package needs no
`serverExternalPackages` entry.
```ts
import { render } from "takumi-pdf/next";
```
### In the browser [#in-the-browser]
The default entry picks its loader from the export conditions the bundler sets.
Vite, webpack, and Turbopack set the same conditions for a browser build.
All three land on the Vite entry, and its `?url` import only works in Vite.
Load the binary yourself instead:
```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.
# Invoices (/docs/pdf/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 [#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}
;
```
Wrap the totals block the same way. It is the part a reader most expects to see whole.
## Electronic invoices [#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.
| 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 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](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]
Public-sector buyers often require an accessible invoice. `tagged: "ua1"` validates the structure tree against PDF/UA-1 during the render. See [PDF/A](/docs/pdf/pdf-a) for what it needs.
## Reproducible bytes [#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.
# Links, outline & metadata (/docs/pdf/links-and-outline)
## 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
,
);
```
Clicking it moves to the page holding that element. A fragment matching no element is dropped, so the reader never gets a link that goes nowhere. Other schemes are dropped too: they have no meaning inside a standalone document.
## Table of contents [#table-of-contents]
`Appendix
| Name | Qty |
|---|
| `, ` | `, and `
let x = 1; , {
fonts: [
{
name: "Geist Mono",
generic: "monospace",
data: () => fetch("https://example.com/GeistMono.woff2").then((res) => res.arrayBuffer()),
},
],
});
}
```
### From Google Fonts [#from-google-fonts]
`googleFonts` fetches families from Google Fonts in one request and returns `fonts` entries: one lazy loader per coverage subset, downloaded when the renderer first needs it. Reference each family by name in `font-family`. [Subsetting](#subsetting) trims them to the content, so unused weights and scripts download nothing.
```tsx twoslash
import { render } from "takumi-js";
import { googleFonts } from "takumi-js/helpers";
const image = await render(Hello 你好 こんにちは , {
width: 1200,
height: 630,
// [!code ++]
fonts: googleFonts(["Inter", "Noto Sans JP", "Noto Sans TC"]),
});
```
Pass an object instead of a name to set a family's weight, style, or variable axes:
```tsx twoslash
import { googleFonts } from "takumi-js/helpers";
await googleFonts([
{
name: "Inter",
weight: [400, 700],
style: "italic",
},
{
name: "Noto Sans JP",
weight: "600..700", // range loads the variable font
},
{
name: "Fraunces",
weight: "100..900",
axes: { opsz: "9..144" }, // vary the optical-size axis too
},
]);
```
Each family accepts:
| Field | Accepts | Effect |
| --------- | ------------------------------------------- | -------------------------------------------------------------------------- |
| `name` | a family name | The family to load. Known families autocomplete their weights and axes. |
| `weight` | a weight, an array, or a range `"100..900"` | A range loads the variable font; CSS `font-weight` drives it. |
| `style` | `"normal"`, `"italic"`, or both | Which styles to fetch. |
| `axes` | `{ tag: value \| "min..max" }` | Variable axes to load, e.g. `{ opsz: "9..144" }`. A range keeps them live. |
| `generic` | a CSS generic family keyword | Every loaded subset claims it, so e.g. `font-mono` resolves to the family. |
Pass an object instead of a list for request-level options:
| Option | Accepts | Effect |
| ---------- | ---------------------- | --------------------------------------------------------- |
| `families` | the list above | The families to load, in fallback priority order. |
| `display` | a `font-display` value | Maps to CSS `font-display`. |
| `cache` | a `Map` | Reuses the metadata CSS across renders. |
| `baseUrl` | a css2 endpoint | Point at a mirror such as `https://fonts.bunny.net/css2`. |
Each subset registers under its own internal name; `font-family: Inter` expands across all of them, so each script finds the file that covers it.
### Subsetting [#subsetting]
`render` registers only the subsets the content draws, so the same `fonts` work for any text and unused ranges never download. The pass runs automatically.
| Font kind | Behavior |
| ----------------------------------- | ------------------------------------------- |
| Ranged subsets (from `googleFonts`) | Trimmed to the codepoints the content uses. |
| Whole files (URL string, raw bytes) | No `unicode-range`, so they load in full. |
To trim before the render, call `subsetFonts({ fonts, source })`, where `source` is the string, node, or node array you render.
### Preloading with `registerFont` [#preloading-with-registerfont]
`registerFont` is the escape hatch for preloading. Register a font on a renderer up front, outside the request path, and reuse that renderer. It takes the same entries as `fonts` and returns the families it made.
```tsx
import { Renderer } from "@takumi-rs/core";
const renderer = new Renderer();
await renderer.registerFont({ name: "Inter", data: inter });
return new ImageResponse(
Variable Font Text
```
Register a variable font once, with no `weight`, and its axes stay live:
```tsx
// a `weight` here pins the file to that instance instead
await renderer.registerFont({ name: "Fraunces", data: variableWoff2 });
```
`googleFonts` does this for you: a weight range or an `axes` entry fetches the variable file and leaves its axes free.
No faux bold
```
Values are `weight`, `style`, or `none`. Pass `weight`, `style`, or both to allow each one; `none` disables them. Emoji never get a fake bold.
## Styling text [#styling-text]
### Color, stroke, and fill [#color-stroke-and-fill]
`color` accepts modern CSS color spaces:
* `rgb`
* `hsl`
* `oklch`
* `lab`
* `display-p3`
* and more
Outline glyphs with `-webkit-text-stroke`. Set a separate fill with `-webkit-text-fill-color`.
```tsx
Outlined
```
The stroke color defaults to `color` when you omit it.
### Decoration & transform [#decoration--transform]
`text-decoration` draws `underline`, `line-through`, and `overline`. Combine them, and set color and thickness. `text-transform` changes the case.
```tsx
Marked up
```
### Shadow [#shadow]
`text-shadow` takes offset, blur, and color. Stack layers with commas.
```tsx
Glow
```
### Spacing & alignment [#spacing--alignment]
`letter-spacing`, `word-spacing`, `line-height`, `text-indent`, and `text-align` (including `justify`) work as in the browser.
```tsx
Body copy
```
## Flowing text [#flowing-text]
### Wrapping [#wrapping]
Takumi supports `balance` and `pretty` wrapping, adapted from [satori](https://github.com/vercel/satori/blob/2a0878a7f329bdba3a17ad68f71186a47add0dde/src/text/index.ts#L365). `balance` evens out line lengths. `pretty` stops the last line from stranding one word.
```tsx
Super Long Text
```
`word-break` and `overflow-wrap` decide where a long token splits. `break-all`, `keep-all`, and `anywhere` cover CJK (Chinese/Japanese/Korean) and long URLs.
### Truncation [#truncation]
When `text-overflow` is `ellipsis`, Takumi truncates at the `line-clamp` count or the container's max height, whichever comes first. Multiline ellipsis works; no `white-space: nowrap` needed.
```tsx
Super Long Text
```
### Fit to container [#fit-to-container]
`text-fit` scales text to fit its line box instead of wrapping or overflowing. The mode comes first: `grow`, `shrink`, or `none`. An optional target and percentage cap follow.
```tsx
Headline that always fits
Per-line scaled, capped at 150%
```
The optional target controls which lines share a scale:
| Target | Effect |
| ---------------------- | --------------------------------- |
| `consistent` (default) | One scale for the whole block. |
| `per-line` | Scales each line except the last. |
| `per-line-all` | Scales every line. |
The percentage caps how far the scale can move.
### RTL & bidirectional text [#rtl--bidirectional-text]
Takumi handles Right-to-Left scripts like Arabic and Hebrew, including mixed runs. There's no manual override for text direction yet (see [issue #330](https://github.com/kane50613/takumi/issues/330)). The `direction` property controls layout, not the text run.
### Language-aware text [#language-aware-text]
The `lang` attribute sets the BCP-47 language for a node. Descendants inherit it, and a nested `lang` overrides. It drives locale-aware shaping: Han unification (one code point draws a different glyph for `zh-Hans`, `zh-Hant`, `ja`, or `ko`) and language-correct line breaking.
```tsx
日本語 繁體中文
{/* Your content here */}
```
## JavaScript / TypeScript [#javascript--typescript]
### Unified runtime detection and fallback [#unified-runtime-detection-and-fallback]
`takumi-js` now detects the right bindings for your environment (Node.js, Workers, and others). You no longer import NAPI (native Node addon) or WASM (WebAssembly) bindings directly.
```ts
import { ImageResponse } from "@takumi-rs/image-response"; // [!code --]
import { ImageResponse } from "takumi-js/response"; // [!code ++]
```
### `emoji` option for dynamic emoji loading [#emoji-option-for-dynamic-emoji-loading]
To match Next.js's `ImageResponse` API, `takumi-js` adds an `emoji` option for a custom emoji provider.
It defaults to `twemoji`. To source emoji glyphs from a font, set it to `from-font` and include an emoji font in `fonts`.
See [Images & emoji](/docs/load-images).
```tsx
import { ImageResponse } from "takumi-js/response";
import notoEmojiFont from "@fontsource/noto-color-emoji/files/noto-color-emoji-emoji-400-normal.woff2";
export function GET() {
return new ImageResponse(It works! 😀 , {
emoji: "from-font", // [!code ++]
fonts: [
{
name: "Noto Color Emoji",
data: notoEmojiFont,
},
],
});
}
```
### Lowercase image formats [#lowercase-image-formats]
Image format options in `@takumi-rs/core` now take lowercase strings only.
```ts
const image = await renderer.render(node, {
format: "WebP" // [!code --]
format: "webp" // [!code ++]
});
```
### `putPersistentImage()` takes `ImageSource` [#putpersistentimage-takes-imagesource]
`renderer.putPersistentImage()` no longer accepts a raw `Buffer` as the second argument. Pass an `ImageSource` object instead.
```ts
const data = await readFile("foo.png");
await renderer.putPersistentImage("foo.png", data); // [!code --]
await renderer.putPersistentImage({ src: "foo.png", data }); // [!code ++]
```
|
|---|