MapLibre Fonts and Glyphs

MapLibre doesn't render text with fonts installed on the machine by default. It fetches precomputed glyph images from a server, or (GL JS, since 5.11.0) falls back to local/system fonts. This skill covers where glyphs come from, the GL JS local-font fallback, MapLibre Native's separate font-faces mechanism, and non-Latin script support. For font sizing, weight, and other visual-hierarchy decisions, see maplibre-cartography.

When to Use This Skill

• Text labels aren't rendering, or render in the wrong font
• Setting up a glyphs URL for a custom or self-hosted style
• Deciding whether to self-host existing font PBFs or generate your own from a TTF/OTF
• Rendering non-Latin scripts (CJK, Arabic, Hebrew, Devanagari, and others)
• Rendering fonts locally/offline without a glyphs server, on GL JS or Native

MapLibre renders text using SDF glyphs

MapLibre renders text using SDF (signed-distance field) glyphs — precomputed font files that scale cleanly at any zoom or screen density, served from a URL matching the style's glyphs field. In GL JS ≥ 5.11.0 (PR #4564), an unresolvable glyphs situation is no longer fatal: MapLibre renders text locally via TinySDF instead, treating text-font as a cascading list of local/web font names. This covers two cases:

• glyphs omitted entirely. A first-class local-fonts mode, not just error recovery. Every text-font name is resolved as a web font (loaded with @font-face or document.fonts.load()) or a system font, the same way a browser resolves a CSS font-family list. No PBF generation, no glyph server. See the local fonts and web fonts examples.
• glyphs is set but a specific glyph PBF fails to load (wrong font name, 404, etc.). The same local-render path fires per glyph range instead of failing the tile, logging Unable to load glyph range ... Rendering codepoint U+... locally instead. Treat this as cosmetic, not correctness: the text renders in a generic local/system font that varies by OS/browser, but doesn't go invisible or break the layer.