maplibre-fonts-glyphs
Configuring fonts and glyphs for MapLibre GL JS and MapLibre Native — the style's `glyphs` URL, self-hosting or generating font PBFs, the GL JS local-font fallback (omitted `glyphs` or a failed glyph fetch), the `font-faces` property both SDKs read, and CJK, right-to-left and Devanagari script handling. Use when text labels aren't rendering in the intended font, setting up a glyphs server, choosing between self-hosting and generating font PBFs, or handling non-Latin scripts.
maplibre · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add maplibre/maplibre-agent-skills --skill maplibre-fonts-glyphs技能说明
name: maplibre-fonts-glyphs
description: Configuring fonts and glyphs for MapLibre GL JS and MapLibre Native — the style's glyphs URL, self-hosting or generating font PBFs, the GL JS local-font fallback (omitted glyphs or a failed glyph fetch), the font-faces property both SDKs read, and CJK, right-to-left and Devanagari script handling. Use when text labels aren't rendering in the intended font, setting up a glyphs server, choosing between self-hosting and generating font PBFs, or handling non-Latin scripts.
metadata:
status: verified
MapLibre Fonts and Glyphs
MapLibre draws label text from precomputed glyph images that a server provides, or, for some scripts and setups, with local or web fonts. This skill covers where glyphs come from, the GL JS local-font fallback, the font-faces property, 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
glyphsURL 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
Don't use this skill to pad an unrelated answer. Fonts and glyphs only affect symbol layers that set text-field. A question about terrain, hillshade, or any other layer that draws no text gets a normal, focused answer that leaves fonts, glyphs, font-faces, and label scripts out entirely, caveats, troubleshooting rows, and optional label sections included.
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:
glyphsomitted entirely. A first-class local-fonts mode, not just error recovery. Everytext-fontname is resolved as a web font (loaded with@font-faceordocument.fonts.load()) or a system font, the same way a browser resolves a CSSfont-familylist. No PBF generation, no glyph server. See the local fonts and web fonts examples.glyphsis 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, loggingUnable 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.
On GL JS, prefer local and web fonts to font stacks. Omit glyphs and load any font the browser lacks as a web font under the name text-font uses. Keep serving font stacks from a glyphs URL only when the style must also work on older GL JS, which requires one, or on MapLibre Native, which has no equivalent of omitting it (tracked, still open: maplibre-native#165).
font-faces names font files for text-font names, and both SDKs read it. The style's root font-faces property maps each text-font name to one or more font files, each optionally limited to a unicode-range. Characters those files cover are drawn from them, and everything else falls back to the glyphs URL. Native has read it since Android 11.13.0 and iOS 6.18.0, with HarfBuzz shaping, and GL JS since 6.7.0, with map.setFontFaces() to change it at runtime. GL JS loads the files through the browser, so each url must be one the browser can fetch: a Native config whose URLs point at files on the device needs URLs the web app serves before GL JS can use it.
Setting the glyphs URL
The style's glyphs field is a URL template ending in /{fontstack}/{range}.pbf (e.g. https://demotiles.maplibre.org/font/{fontstack}/{range}.pbf), where {fontstack} is the comma-joined text-font list and {range} a Unicode range — full mechanics: style spec — glyphs. text-font is itself a fallback list — see Noto for global maps below.
Font options
| Source | Fonts available | Notes |
|---|---|---|
demotiles.maplibre.org/font | Noto Sans (Latin, Arabic, CJK, etc.), Noto Sans Bold, Italic | Free, publicly hosted; good for prototyping |
OpenMapTiles fonts.openmaptiles.org | Klokantech Noto Sans family | Matched to OMT schema styles |
| Self-hosted, existing font | Reuse prebuilt PBFs (openmaptiles/fonts, UNDP-Data/fonts, or your current server's tree) | Full control; no generation needed for standard fonts |
| Self-hosted, custom font | Generate PBFs from your own TTF/OTF |