Fonts & images

Pass fonts through fonts and image bytes through images. The renderer fetches neither on its own. Font URL loaders and googleFonts() make their own requests, and you fetch document images before rendering.

FontsCopy Anchor Link

import { render } from "takumi-pdf";

import { googleFonts } from "@takumi-rs/helpers";

const pdf = await render(doc, {
  fonts: [...(await googleFonts(["Inter"])), { name: "Brand Sans", weight: 700, data: fontBytes }],
  fontFamilies: ["Brand Sans", "Inter", "sans-serif"],
});

fonts takes font URLs, raw bytes, descriptors, or googleFonts() entries. fontFamilies sets the fallback chain. A reused renderer loads each font once.

For offline renders, bundle font files. Google Fonts requests use the shared fetch limits and retries.

CoverageCopy Anchor Link

The renderer does not read system fonts. Its only built-in font is Geist, a last-resort face for Latin text. By default, a character that no registered font covers fails the render, and the error names the character and its codepoint.

Register fonts for every script you use. Google Fonts can split accented letters between its latin and latin-ext subsets.

Family namesCopy Anchor Link

Quote a family name when one of its words starts with a digit, such as fontFamily: '"Source Serif 4"'. Unquoted, Source Serif 4 is not a valid font-family value. The declaration is dropped and the text falls back to the next family.

Uncovered textCopy Anchor Link

uncoveredText sets what happens to a character that no registered font covers:

Neither "placeholder" nor "blank" reflows the line. The character keeps the width it had during layout.

import { render } from "takumi-pdf";

const pdf = await render(doc, { uncoveredText: "placeholder" });

Standards forbid the placeholderCopy Anchor Link

Every PDF/A level and both PDF/UA levels forbid glyph 0. "placeholder" fails the render with any pdfa level, tagged: "ua1", or tagged: "ua2". The error names the uncovered characters and the standard. Use "blank" there. See PDF/A and PDF/UA.

What copied text keepsCopy Anchor Link

Whether an uncovered character survives in copied text depends on its shaping cluster. This holds for "placeholder" and "blank" alike.

ImagesCopy Anchor Link

Pass the bytes for each image URL in the document. The renderer does not fetch them:

import { render } from "takumi-pdf";

const response = await fetch(logoUrl);
if (!response.ok) throw new Error(`Logo request failed: ${response.status}`);
const logoBytes = new Uint8Array(await response.arrayBuffer());

const pdf = await render(doc, {
  images: [{ src: logoUrl, data: logoBytes }],
});

To fetch every remote image in a tree at once, use prepareImages().

FormatsCopy Anchor Link

Identical raster images are embedded once.

FiltersCopy Anchor Link

A CSS color filter on an image needs decoded pixels, and the PDF build decodes only PNG. A filtered JPEG or WebP image fails the render.

PDF output also rejects filter: blur() and drop-shadow(), naming the function in the error. Bake those effects into a raster image before rendering.