MapLibre Sprites and Icons

An icon on a MapLibre GL JS map is either part of the map, drawn by a symbol layer from a sprite (a PNG atlas plus a JSON index served from the style's sprite URL) or from an image registered at runtime with addImage, or on top of the map as a Marker, outside the style. For icon color, halos, and figure-ground against imagery, see maplibre-cartography; for text and glyph setup, see maplibre-fonts-glyphs.

When to Use This Skill

• Choosing between a Marker, a sprite, and addImage for icons on a map
• A symbol layer's icons do not render
• Adding your own icon sheet to a style whose sprite you do not control
• Setting up, self-hosting, or building a sprite from SVGs (for glyphs, see maplibre-fonts-glyphs)
• Registering icons, including SVGs, for a layer your app adds at runtime
• Route shields render as bare numbers or missing badges
• Writing tooling that reads or generates symbol layers and has to recognize a shield

Choosing a Marker, a sprite, or addImage

Two questions, in order; the sections below follow them.