effect-motion
Guides

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.

0:00
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",	),);

On this page