Load custom fonts
Fonts are typed scene dependencies — declare, load once, render everywhere
Text renders in a built-in sans-serif with zero setup. A custom face is a typed resource: the scene declares it, and every consumer (player, export) must provide a loader for it — checked at compile time.
Declare
import * as Font from "effect-motion/Font";
const Pacifico = Font.Font("Pacifico");Font.Font(id) creates a constant that is itself an Effect. Yielding it
inside a scene returns the font handle for fontFamily — and adds
FontLoader<"Pacifico"> to the scene's requirements:
const pacifico = yield* Pacifico;
yield* Scene.instantiate("Text", { text: "hello", fontFamily: pacifico });Provide
A loader layer pairs the constant with an effect producing the font bytes:
export const renderLayers = Font.layer(
Pacifico,
Resource.fetchBytes("https://…/Pacifico_400Regular.ttf"),
);In the browser, pass it to the Player as renderLayers — the prop is
required by the type system once the scene declares any resource. In
Node (export), provide the same layer with Effect.provide; the load
effect can read from disk there instead of fetching. For font files in
your project, one loader can do both; see
Load files from your project.
The load runs once at mount, before anything renders — the first visible
frame is already in the right face, no fallback flash. Multiple fonts merge
with Layer.mergeAll.
Pass fonts to helpers
A yielded handle is typed with its id: Font.Font<"Pacifico">. A helper
that should accept any font takes the wide type, Font.Font:
const title = (text: string, font: Font.Font) =>
Scene.instantiate("Text", { text, fontFamily: font, fontSize: 120 });
yield* title("hello", yield* Pacifico);Annotating the parameter as Font.Font<"Pacifico"> accepts only that one
font. Images work the same way with Image.Image.
import * as Color from "effect-motion/Color";import * as Entity from "effect-motion/Entity";import * as Font from "effect-motion/Font";import * as Motion from "effect-motion/Motion";import * as Resource from "effect-motion/Resource";import * as Scene from "effect-motion/Scene";// Fonts are typed scene dependencies: yielding the constant puts// FontLoader<"Pacifico"> into the scene's requirements, and the player will// not compile without a covering renderLayers. The load runs once at mount,// so the first visible frame is already in Pacifico.const Pacifico = Font.Font("Pacifico");export const scene = Scene.make( "custom fonts", function* () { const pacifico = yield* Pacifico; const custom = yield* Scene.instantiate("Text", { position: Entity.vec3({ y: 110 }), text: "Custom fonts", fontSize: 160, fontFamily: pacifico, fillColor: Color.hex("#7f5af0"), textAnchor: "middle", baseline: "middle", opacity: 0, }); // no fontFamily: the built-in default face — zero ceremony, no requirement const plain = yield* Scene.instantiate("Text", { position: Entity.vec3({ y: -140 }), text: "vs the default sans-serif", fontSize: 64, fillColor: Color.hex("#94a3b8"), textAnchor: "middle", baseline: "middle", opacity: 0, }); yield* custom.pipe(Motion.fadeTo(1, "600 millis")); yield* plain.pipe(Motion.fadeTo(1, "600 millis")); yield* Motion.wait("1 second"); }, { width: 1920, height: 1080, backgroundColor: Color.rgba(22, 22, 29) },);// a CORS-open, version-pinned TrueType file; in Node the same layer could// read the bytes from disk insteadexport const renderLayers = Font.layer( Pacifico, Resource.fetchBytes( "https://cdn.jsdelivr.net/npm/@expo-google-fonts/pacifico@0.2.3/Pacifico_400Regular.ttf", ),);