Fonts

Core measures text and converts glyph outlines into paths during layout. SVG serialization needs no font access, and PNG rasterization needs no font registration: the SVG already contains the geometry. The layout host still needs font data to produce those paths.

Bundled faces

IBM Plex Sans and IBM Plex Mono are bundled at weights 300, 400, and 700. The default is IBM Plex Sans, 400, normal, 16px. Family names must match registered names. The provider chooses the nearest available weight, preferring the lower weight on a tie. If no italic face is available, an italic request uses an oblique transform of the normal outline.

There is no system-font discovery or automatic fallback-family chain. An unknown family or missing glyph is an error, rather than a silently substituted font. In particular, do not assume arbitrary emoji or scripts are covered by the bundled faces. Emoji are the exception, as described below, and a host can opt in to further fallback faces.

Host setup

A default LayoutPass supplies Fonts. In Bun, bundled files load lazily on first use. Browser hosts should preload the needed family before layout and arrange for the bundled font assets to be served:

import { Fonts, LayoutPass, sans, regular } from '@gum-jsx/core' const fonts = new Fonts() await fonts.load(sans) // Omit the family to load all bundled faces. const pass = new LayoutPass({ fonts: { value: fonts, version: fonts.version } })

For your own font, register the bytes of an individual face, not a font collection. This Bun example uses an application-provided file:

const bytes = await Bun.file('./assets/MyFont-Regular.ttf').arrayBuffer() fonts.register('My Font', bytes, { weight: regular, style: 'normal' }) pass.set_resource('fonts', fonts, fonts.version)

register accepts ArrayBuffer or Uint8Array and owns a copy. Registration bumps fonts.version; notifying a reused pass invalidates cached geometry. A fresh pass can simply receive the latest value/version. A custom FontProvider may be injected through the same resource slot if the host supplies its own shaping and outline implementation.

Omit the family argument to infer the family, weight, and style from the font's metadata. This form returns the registered family name; optional settings can override the metadata or provide an alias:

const family = fonts.register(bytes) fonts.register(bytes, { family: 'My Alias', weight: 400 }) const result = render_element(figure, { fonts, defaults: { font_family: family }, })

The preferred typographic family groups extended weights with their regular and bold faces. The explicit register('My Font', bytes, options) form retains its 400/normal defaults. Defaults in render_element or layout_element are inherited; explicit font choices in the source take precedence.

The CLI loads extra faces; select the inherited family in JSX:

<Page font-family="Inter"> <Text>Text inherits the document's font.</Text> </Page>

Repeat --font for individual faces; paths resolve from the invoking directory. The family comes from the file metadata, not its filename. Font collections are not supported, and variable fonts use their default instance. Loading fonts alone leaves Plex Sans as the default. font-family also accepts bundled families such as "IBM Plex Mono". These props work in figures, decks, and video.

Math font selection is separate from prose. Load a font with --font and select its family with the inherited math-font prop:

<Page font-family="IBM Plex Sans" math-font="My Math"> <Text> A formula: <Tex>x^2 + y^2</Tex> </Text> </Page>

Nested elements and spans can override math-font. In library calls the prop is math_font, including mathToSvg(tex, { fonts, math_font: 'My Math' }).

The KaTeX provider uses the selected font's ordinary glyphs and Unicode italic/double-struck alphabets where covered, with bundled fallbacks for missing glyphs, other styles, and large size-font symbols. It retains KaTeX layout parameters and stretchy constructions; OpenType MATH tables are not read. Library hosts pass new KatexMathFontProvider('My Math') as the layout pass's math_fonts resource, alongside the ordinary font registry.

Fallback faces and emoji

Emoji work in ordinary text with no setup. Color fonts are not outlined, because a bitmap or layered glyph is not one filled path. Core instead bundles a small metrics face for Noto Color Emoji, which only measures, and the SVG carries each emoji as live text such as <text font-family="'Noto Color Emoji'">. The page that displays the SVG should provide that family, for example through an @font-face rule; otherwise the viewer's own emoji font paints each emoji, centered in its measured advance. PNG output depends on the rasterizer's own font support, and PDF output reports live text as an error.

Register a face with fallback: true to receive other text that the requested family cannot shape. Fallback families apply in registration order, after the bundled emoji face, and whole grapheme clusters move together:

const bytes = await Bun.file('./assets/NotoSansJP-Regular.ttf').arrayBuffer() fonts.register('Noto Sans JP', bytes, { fallback: true })

Fonts is a host API, not a default JSX evaluator binding. The runnable example uses only the bundled families and needs no setup beyond the CLI.