Skip to Content
Takumi

render()

Every option render() takes, grouped by what it sets, and what it returns.

render() lays out JSX, an HTML string, or a node tree across pages and resolves to the PDF bytes, a Uint8Array.

Render a document
import {  } from "takumi-pdf";

const  = await ("<h1>Invoice 1042</h1>", { : "letter", : true });

It uses one renderer shared by every call. To keep a font registry of your own, call render() on a PdfRenderer, which takes the same options.

Page

These options lay content out across pages. They can't be combined with viewport.

Prop

Type

Description

size?"a3" | "a4" | "a5" | "b4" | "b5" | "jis-b4" | "jis-b5" | "ledger" | "legal" | "letter" | { width, height }

Page size. An object is in CSS px at 96 dpi. A `@page` rule wins over it.

landscape?boolean

Swaps the page width and height, explicit sizes included.

margin?number | "auto" | { top?, right?, bottom?, left? }

Page margin in CSS px. `"auto"` fits the header or footer on that side.

header?JSX | string | Node | false

A band repeated in the top margin of every page.

footer?JSX | string | Node | false

A band repeated in the bottom margin of every page.

pages?{ first?, last?, odd?, even? }

Replaces the header or footer on some pages. Each field takes `{ header?, footer? }`.

pageRanges?(number | { from?, to? })[]

The pages the file keeps, counted from 1. Page numbers still count every page.

Single page

Prop

Type

Description

viewport?{ width: number; height?: number }

Renders one page of this size in CSS px, like an image. Without `height`, the page is as tall as the content.

Content

Prop

Type

Description

css?CssInput | CssInput[]

Stylesheets applied before layout, cascading in order. `@page` rules here set the page.

fonts?FontLoader[]

Fonts to load: URLs, bytes, descriptors, or `googleFonts()` entries. A loaded font is reused while the renderer's cache keeps it.

fontFamilies?string[]

The families text falls back through, in order.

images?ImageLoader[] | { sources?, cache? }

Images by `src`, so the render doesn't fetch them.

lang?string

The BCP 47 language of the root element. Tagged output and metadata use it too.

uncoveredText?"error" | "placeholder" | "blank"

What a character no font covers becomes. `"error"` fails the render and names the character.

backgroundColor?string

A CSS color painted under everything on every page, margins included.

Document

Prop

Type

Description

metadata?{ title?, description?, authors?, keywords?, creator?, creationDate?, xmp? }

The document properties a viewer shows. `creationDate` is UTC, and setting it keeps the bytes reproducible.

outline?boolean

Adds bookmarks for `h1` to `h6` headings.

attachments?{ name, data, mimeType?, description?, relationship?, modificationDate? }[]

Files embedded in the PDF, such as invoice XML.

pdfa?"2a" | "2b" | "2u" | "3a" | "3b" | "3u" | "4" | "4f"

A PDF/A level to write and validate. A file that fails validation rejects the render.

tagged?boolean | "ua1" | "ua2"

Writes the structure tree, and with `"ua1"` or `"ua2"` validates it against PDF/UA.

signal?AbortSignal

Stops the render before it reads or draws the document.

The types reject combinations a standard forbids. For example, pdfa: "2a" with tagged: false, or attachments with a PDF/A-2 level, fail to typecheck. See Compatible options.

Last updated on