Fonts

Load a font for every script your text uses.

Loading fontsCopy Anchor Link

The fonts optionCopy Anchor Link

Pass the fonts a render needs through fonts. Each entry takes one of three forms:

render, renderSvg, renderAnimation, measure, and ImageResponse all take fonts. It also takes a promise of the list, so pass googleFonts(...) without await.

The renderer decodes each file once and keeps it until you release it, or until fontCacheMaxBytes evicts it.

import { ImageResponse } from "takumi-js/response";

export function GET() {
  return new ImageResponse(<div>Hello Takumi</div>, {
    fonts: ["https://example.com/Inter.woff2"], 
  });
}

A descriptor's data is raw bytes or a function that returns them:

import { ImageResponse } from "takumi-js/response";

export function GET() {
  return new ImageResponse(<div>Hello Takumi</div>, {
    fonts: [
      {
        name: "Inter",
        weight: 700,
        data: () => fetch("https://example.com/Inter.woff2").then((res) => res.arrayBuffer()),
      },
    ],
  });
}

generic assigns the font to a CSS generic family keyword. A stack that ends in monospace or serif then reaches the font without naming it. This is how Tailwind's font-mono finds it:

import { ImageResponse } from "takumi-js/response";

export function GET() {
  return new ImageResponse(<div tw="font-mono">let x = 1;</div>, {
    fonts: [
      {
        name: "Geist Mono",
        generic: "monospace", 
        data: () => fetch("https://example.com/GeistMono.woff2").then((res) => res.arrayBuffer()),
      },
    ],
  });
}

From Google FontsCopy Anchor Link

import { render } from "takumi-js";
import { googleFonts } from "takumi-js/helpers";

const image = await render(<div style={{ fontFamily: "Inter" }}>Hello 你好 こんにちは</div>, {
  width: 1200,
  height: 630,
  fonts: googleFonts(["Inter", "Noto Sans JP", "Noto Sans TC"]),
});

googleFonts makes one CSS request for all the families. Font files download only when the text needs them; see subsetting. Use the family name in fontFamily.

Pass an object instead of a name to set a family's weight, style, or variable axes:

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
  },
]);

Pass an object instead of an array for request options:

import { googleFonts } from "takumi-js/helpers";

const fonts = await googleFonts({
  families: ["Inter"],
  timeout: 3000, 
});

googleFonts also takes the fetch options: timeout, signal, maxBytes, allowUrl, and fetch. The timeout covers each request on its own: the CSS request, then each font file. It does not cover the whole render.

The default CSS cache is bounded and shares concurrent requests for the same URL. A request with signal or allowUrl skips the cache, so cancellation and URL checks stay with the caller. maxBytes applies to cache hits too.

Fonts in CI and offline rendersCopy Anchor Link

Bundle font files when a render must work without Google Fonts:

import { readFile } from "node:fs/promises";
import { render } from "takumi-js";

const inter = await readFile(new URL("./fonts/Inter.woff2", import.meta.url));

const image = await render(<div style={{ fontFamily: "Inter" }}>Hello</div>, {
  fonts: [{ name: "Inter", data: inter }],
});

Retries recover a brief outage. They do not help when the host is down or the CI network blocks it. Run unit tests against local files or an injected fetch, and test the live service separately.

An outer test or route timeout can end the render before the font timeout does. Set timeout below that outer limit, and leave time for layout and encoding.

CJK families can have many coverage subsets. Takumi downloads only the subsets your text uses. Matching subsets from several families or weights still download together, so request only the families and weights you use. A timeout during await googleFonts(...) comes from the CSS request, before any font file downloads.

SubsettingCopy Anchor Link

render registers only the subsets the content draws. The same fonts list works for any text, and unused ranges never download. This runs on every render.

To filter a list yourself, call subsetFonts({ fonts, source }) from takumi-js/helpers. source is the string, node, or node array you render.

Preloading with registerFontCopy Anchor Link

To load fonts before the first request, register them on a renderer. Then pass that renderer to each render. registerFont takes the same entries as fonts and returns the families it added.

import { readFile } from "node:fs/promises";
import { Renderer } from "takumi-js/node";
import { ImageResponse } from "takumi-js/response";

const inter = await readFile(new URL("./fonts/Inter.woff2", import.meta.url));
const renderer = new Renderer();

await renderer.registerFont({ name: "Inter", data: inter }); 

export function GET() {
  return new ImageResponse(<div style={{ fontFamily: "Inter" }}>Hello Takumi</div>, {
    width: 1200,
    height: 630,
    renderer, 
  });
}

Releasing fontsCopy Anchor Link

A renderer keeps every font it loads. Release the ones you no longer need:

renderer.unregisterFont({ name: "Inter" }); // every face and subset of Inter
renderer.clearFonts(); // back to the built-in Geist

A later render that lists a released font loads it again.

To release fonts automatically, cap the decoded bytes that fonts lists may keep:

const renderer = new Renderer({ fontCacheMaxBytes: 64 * 1024 * 1024 });

Past the cap, the least recently used families go first. Fonts from registerFont always stay. The font loaded last also stays, even if it alone exceeds the cap. Set the cap above what one render needs.

Choosing a fontCopy Anchor Link

Fallback chainCopy Anchor Link

fontFamilies is the ordered list of families to try when a glyph is missing. Set it to choose which family wins and what backs it up.

import { render } from "takumi-js";
import { googleFonts } from "takumi-js/helpers";

const image = await render(<div>Hello こんにちは</div>, {
  fonts: googleFonts(["Inter", "Noto Sans JP"]),
  fontFamilies: ["Inter", "Noto Sans JP"], 
});

Without fontFamilies, the chain is the render's fonts in list order. A render without fonts uses every registered family in registration order. Geist always comes last.

A missing glyph walks the chain until a family covers it. googleFonts registers every subset under its family name with its unicode-range. Each character then uses the subset that covers it, as in a browser.

Variable axes & OpenType featuresCopy Anchor Link

Set font axes with font-variation-settings and OpenType features with font-feature-settings. In a variable font, font-weight drives the wght axis and font-stretch drives wdth. Kerning is on by default; font-kerning: none turns it off.

<div
  style={{
    fontFamily: "Fraunces",
    fontVariationSettings: "'opsz' 72, 'wght' 700",
    fontFeatureSettings: "ss01",
  }}
>
  Variable Font Text
</div>

Register a variable font once, with no weight, to keep its axes live:

// 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.

Synthetic bold & italicCopy Anchor Link

When a family lacks the weight or style you asked for, Takumi draws a synthetic bold or oblique. font-synthesis controls this.

<div style={{ fontFamily: "Inter", fontSynthesis: "none" }}>No faux bold</div>

List weight, style, small-caps, or any mix of them to allow each one. none turns them all off, so a missing bold weight draws at regular weight.

Typography covers styling text and controlling how it flows.