Fonts and languages
The fonts the engine ships, how Arabic, Bengali and Devanagari fonts load on demand, any Google Fonts family by name, right-to-left text in both targets, and how to add fonts such as CJK.
The engine compiles with its own fonts, not the reader's system fonts, so a page looks the same on every machine and in the exported PDF. It ships a small base set and downloads fonts for other scripts only when a document uses them. This page covers both, letting documents use any Google Fonts family, right-to-left text, and how to add fonts of your own.
The fonts the engine ships
| Fonts | Covers | Loaded |
|---|---|---|
| Libertinus Serif (regular, bold, italic) | Latin, Greek, Cyrillic, Hebrew | When the engine starts |
| New Computer Modern Math | Math | When the engine starts |
| DejaVu Sans Mono | Raw text and code | When the engine starts |
| The rest of Typst's bundled faces: Libertinus Serif bold italic and semibold, New Computer Modern, the math font's regular and bold, DejaVu Sans Mono bold and oblique | What a document asks for (*_bold italic_*, bold code, math in bold text, symbols Libertinus Serif lacks) | The first time a document uses it |
| Noto Naskh Arabic (regular, bold) | Arabic | The first time a document uses it |
| Noto Serif Bengali (regular, bold) | Bengali | The first time a document uses it |
| Noto Serif Devanagari (regular, bold) | Devanagari (Hindi, Marathi, Nepali, …) | The first time a document uses it |
The base fonts are about 2.6 MB. Each script font file is 47–79 KB compressed and is fetched on its own, so a
document with regular-weight Arabic text downloads one file. All of them are served from your own origin: your
bundler emits them as assets next to @typstream/engine-wasm's JavaScript. Their licenses are in
@typstream/engine-wasm's dist/fonts/NOTICE and dist/fonts/LICENSE-Noto.txt.
#set text(size: 16pt)
Good morning, class.
#text(lang: "ar")[صباح الخير يا طلاب.]
#text(lang: "bn")[সুপ্রভাত, শিক্ষার্থীরা।]On a first visit you may see the Arabic and Bengali lines in the Pages view settle a moment after the English one: the first compile lacked their fonts, and the engine compiled again once they arrived.
How lazy fonts load
Script fonts are registered when the engine starts, from metadata computed at build time (family, style, which characters each face covers), but without their bytes. Typst picks fonts as usual, by family or by falling back to the first font that covers the text, so it chooses a script font exactly as if it were loaded. Then:
- The compile notes that it wanted a font it has no bytes for, and carries on: for now the text falls back to the next font or shows as boxes. The compile itself succeeds.
- The engine's worker fetches the font. Fetched fonts are kept in Cache Storage (
typstream-fonts), so each downloads once per browser. - Once the font has arrived, the engine compiles the document again on its own, and the text appears in the right font. You don't need to do anything.
Exports wait for missing fonts too: an export whose compile lacked a font waits up to 3 seconds for it, then compiles again with it, or exports without it if it doesn't arrive in time.
Fonts in the HTML target
In the HTML target the browser draws the text, with the reader's fonts and your CSS. Typst's HTML export leaves fonts
out: #set text(font: "…") changes nothing there. The engine's fonts matter only where Typst draws something itself,
such as the drawings @typstream/html-compat turns into inline SVG (CeTZ canvases, polygons). For Arabic or Bengali in
the HTML target, the reader's system fonts are used unless your page loads web fonts for those scripts. The families a
font catalogue loads are the exception: see the next section.
Math is the exception. Typst writes math as MathML, and browsers need a math font to stretch delimiters and set
math italics. @typstream/html-compat's stylesheet asks for New Computer Modern Math, and typstream's
<Typstream> registers the engine's copy of it as a web font. With @typstream/react, pass its URL yourself:
import { baseFonts } from "@typstream/engine-wasm/fonts";
import { Typstream } from "@typstream/react";
const mathFont = baseFonts.find((url) => url.pathname.includes("NewCMMath"));
<Typstream source={text} mathFont={mathFont} />;Without React, registerMathFont(url) from @typstream/dom does the same. It uses the FontFace API, so it needs no
font-src exception for inline CSS.
Any Google Fonts family
With the @typstream/google-fonts plugin, a document can name any family of the
Google Fonts library, and a model writing one can use whichever suits it:
import { googleFonts } from "@typstream/google-fonts";
import { Typstream } from "typstream";
<Typstream source={text} plugins={[googleFonts]} />;#set text(font: "Lora")
#show heading: set text(font: "Playfair Display")
= Fractions
#text(font: "Caveat")[Show your working.]Pass the plugin to buildSystemPrompt from @typstream/edu too: its prompt rules tell the model it may use any Google
Fonts family by its exact name, and which families stand in for Arial, Times New Roman or Calibri, which aren't in the
library.
How it works
The plugin gives the engine a font catalogue: an index of the library's 2,000 families and their font files
(catalogue.json, 465 KB, 67 KB gzipped), pinned to one commit of
github.com/google/fonts, whose files jsDelivr serves.
- A document names a family the engine doesn't have. Typst warns
unknown font family: lora, and the text falls back to the base fonts for now. - The worker looks the family up in the index (fetched the first time) and downloads its files. Fonts are the worker's, so every document has the family from then on.
- The engine compiles the document again with it, as it does when a lazy font arrives. Exports wait for it too.
In the paged target Typst draws the text with the family's files, as in the PDF. In the HTML target, the
plugin's preamble marks text in another font than the document's own with its family
(<span data-typstream-font="lora">; not inside equations, which keep their math font). When the engine has loaded a
family, mountTypstream (and so <Typstream>) registers the same files as web fonts and shows the marked text in it.
Text in a family that didn't load keeps your page's font. HTML exports (exportHtml) link the families they use.
Limits
- Size. A family whose files add up to more than 5 MB isn't loaded: that leaves out most CJK families (10–20 MB).
createGoogleFonts({ maxBytes })raises the limit. Families that are only one file per style (variable fonts, as most popular ones are) load whole. A static family larger than 1 MB loads only its regular and bold of each style, and Typst gives other weights the nearest of those. - Names. A family must be named exactly as Google Fonts names it (
"Open Sans", not"OpenSans"), case aside. Arial, Helvetica or Calibri aren't in the library: the text keeps the base fonts, and a warning stays. - Network. Readers' browsers download the index and the files from
cdn.jsdelivr.net. Under a Content-Security-Policy, add it toconnect-src(Security). To keep readers off third-party servers, mirror the files and point a copy of the index at your mirror:createGoogleFonts({ index: "/fonts/catalogue.json" }), whosebaseis your mirror's URL. - Node.
@typstream/node's server loads nothing from catalogues.
A catalogue of your own
Any plugin can bring a catalogue, in engine.fontCatalogues: { index, maxBytes? }, where index is the URL of a
JSON file in this shape (FontCatalogueIndex in @typstream/core):
{
"version": 1,
"base": "https://fonts.example.com/files/",
"families": {
"school sans": {
"name": "School Sans",
"files": [
{ "path": "SchoolSans[wght].ttf", "style": "normal", "weight": [300, 800], "bytes": 412000 },
{ "path": "SchoolSans-Italic[wght].ttf", "style": "italic", "weight": [300, 800], "bytes": 431000 }
]
}
}
}Families are keyed by their name lowercased, which is how Typst compares names, and name must be the name in the
font files. Files are TTF or OTF (Typst reads no WOFF); base is relative to the index's URL. Unlike engine.fonts,
a catalogue works from a document's plugins too: it only names fonts, which the worker loads for itself when a document
asks for one. To show its families in the HTML target, add googleFontsPreamble from @typstream/google-fonts to your
plugin's preamble and allow the attribute it writes (sanitize: { allowAttrs: { span: ["data-typstream-font"] } }).
Right-to-left text
Set the language, and Typst sets the direction: #set text(lang: "ar") for a whole document, #text(lang: "ar")[…]
for a passage. @typstream/edu's templates take lang: "ar" and do this for you.
Paged target. Typst lays out right-to-left text itself. The selectable text layer over each page carries the
page's and each run's lang and dir, so selecting, copying and screen readers follow the text's direction.
HTML target. Typst's HTML export writes the document's language but no direction. The renderer adds it: it sets
lang and dir on its root element from the document's language, which orders lists and tables right to left.
Within the document, the theme gives paragraphs, list items, headings and table cells unicode-bidi: plaintext, so
each takes its direction from its first strong letter: an Arabic paragraph in an English document aligns right, and
the other way round. Standalone HTML exports get dir="rtl" on <html> the same way.
Add your own fonts
CJK fonts aren't in the default set (one weight of Noto Serif SC is 11.6 MB), and you may want a brand font. Fonts
are given to the engine as FontSources:
| Shape | Loaded |
|---|---|
{ kind: "url", url, info } | Lazily: registered from info, fetched the first time a document uses it. |
{ kind: "url", url } | When the engine starts. |
{ kind: "bytes", data } | When the engine starts. |
family and scripts (ISO 15924 codes, such as ["Hani"]) are informational. The URL is fetched by the engine's
worker, so give an absolute URL; under a strict Content-Security-Policy it must be allowed by connect-src.
Beta
FontSource, the plugin facet engine.fonts and createEngine's initialize are @beta.
Compute info
info is the engine's metadata for the file: Typst's FontInfo for each face, as JSON. Compute it once, at build
time, with the version of @typstream/engine-wasm your app ships:
import { readFileSync } from "node:fs";
import { createRequire } from "node:module";
import { Engine, initSync } from "@typstream/engine-wasm";
const require = createRequire(import.meta.url);
initSync({ module: readFileSync(require.resolve("@typstream/engine-wasm/engine_bg.wasm")) });
const info = Engine.font_info(readFileSync(process.argv[2]));
console.log(`export const info = ${JSON.stringify(info)};`);node scripts/font-info.mjs public/fonts/NotoSerifSC-Regular.otf > src/noto-serif-sc-info.tsGive them to the engine
Fonts belong to the engine, not to a document: every document on an engine sees the same fonts. So create an engine with them and hand it to your components:
"use client";
import { type ReactNode, useEffect, useState } from "react";
import { createEngine, type Engine, engineWorker, TypstreamProvider } from "typstream";
import { info } from "../src/noto-serif-sc-info";
export function PreviewProvider({ children }: { children: ReactNode }) {
const [engine, setEngine] = useState<Engine | null>(null);
useEffect(() => {
const created = createEngine({
spawn: engineWorker(),
initialize: {
fonts: [
{
kind: "url",
url: new URL("/fonts/NotoSerifSC-Regular.otf", location.origin).href,
family: "Noto Serif SC",
scripts: ["Hani"],
info,
},
],
},
});
setEngine(created);
return () => created.dispose();
}, []);
if (!engine) return null;
return <TypstreamProvider engine={engine}>{children}</TypstreamProvider>;
}The engine is created in an effect because it starts a Web Worker, which exists only in the browser. Every
<Typstream> under the provider uses it.
A plugin can carry fonts too, in engine.fonts. They load only when the plugin is passed to
createEngine({ plugins }). A plugin given only to a document (the plugins prop) can't add fonts to an engine that
is already running: the engine logs a warning (plugin "…" brings fonts the engine doesn't have) and the document
compiles without them.
Fonts on the server
@typstream/node loads its fonts from disk when a worker starts. By default it has Typst's bundled set (Libertinus
Serif, New Computer Modern, DejaVu Sans Mono) and the three script fonts, all loaded up front. Add more with
fontPaths (directories searched recursively, like typst --font-path) or fonts (file bytes):
import { createEngine, render } from "@typstream/node";
const engine = createEngine({ fontPaths: ["/srv/fonts/noto-cjk"] });
const pdf = await render(source, "pdf", { engine });typstFonts: false and scriptFonts: false leave out the default sets.