maplibre-sprites-icons
Sprites and icon images for MapLibre GL JS — choosing a `Marker`, a sprite, or `addImage`; the `sprite` base URL and its `{id, url}` array form for several sheets; self-hosting and building sprites; runtime images, SVGs included, with `addImage`; finding a missing icon with the console warning and `hasImage`; and route shields that render as bare numbers. Use when deciding how to put icons on a map, when a symbol layer's icons never appear, when adding your own icons to a style whose sprite you do not control, or when shields are missing their badge.
maplibre · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add maplibre/maplibre-agent-skills --skill maplibre-sprites-iconsAbout this skill
name: maplibre-sprites-icons
description: Sprites and icon images for MapLibre GL JS — choosing a Marker, a sprite, or addImage; the sprite base URL and its {id, url} array form for several sheets; self-hosting and building sprites; runtime images, SVGs included, with addImage; finding a missing icon with the console warning and hasImage; and route shields that render as bare numbers. Use when deciding how to put icons on a map, when a symbol layer's icons never appear, when adding your own icons to a style whose sprite you do not control, or when shields are missing their badge.
metadata:
status: verified
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, andaddImagefor icons on a map - A symbol layer's icons do not render
- Adding your own icon sheet to a style whose
spriteyou do not control - Setting up, self-hosting, or building a
spritefrom SVGs (forglyphs, 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.
- Is the icon part of the map, or on top of it? Part of the map means a symbol layer's
icon-image: placed together with the labels, hidden when it collides, and drawn in layer order, for a point dataset of any size. A small number of annotations on top of the map, that people drag or that need their own HTML, areMarkers. - For a symbol layer, where does the image come from?
- The style. POIs, town spots, shields, pattern textures, and any other icon or texture layered into the style, where it takes part in the visual hierarchy and collisions: a sprite. Your own set on a basemap whose sprite you do not control is a second sheet, still a sprite.
- Your app, at runtime. Icons for a layer the app adds, such as a GeoJSON source, that no sheet carries:
addImage. Use it deliberately. Each image is its own request andaddImagecall, where a sprite arrives as one PNG and one JSON, and its icons collide with the style's labels and with each other like sprite icons.
Sprites
The style's sprite value is a base URL with no file extension; MapLibre appends .json, .png, and @2x variants itself.[1] A symbol layer names a sprite image in icon-image (other layers in their *-pattern property), and the name must exactly match an ID in the sprite JSON index or the icon is not drawn.
{
"sprite": "https://example.com/sprites/poi",
"layers": [
{
"id": "cafes",
"type": "symbol",
"source": "places",
"source-layer": "poi",
"layout": { "icon-image": "cafe" }
}
]
}
https://demotiles.maplibre.org/styles/osm-bright-gl-style/sprite works for testing; do not use it in production.
Multiple sprite sheets in one style
sprite is not limited to a single string. Since MapLibre GL JS 3.0 (#1805) it also accepts an array of {id, url} objects,[1] so a style can load its own icons alongside a basemap provider's sheet. Before 3.0 a style could name only one sprite, so adding your own icons meant merging them into the provider's sheet; with the array form, each sheet stays where it is hosted.
{
"sprite": [
{ "id": "default", "url": "https://tiles.openfreemap.org/sprites/ofm_f384/ofm" },
{ "id": "my-icons", "url": "https://example.com/sprites/poi" }
]
}
Rules that follow from that form:
- Reference images by
id:image-name—"icon-image": "my-icons:cafe". An unprefixed"cafe"resolves against thedefaultsheet only. - The
iddefaultis the one exception: its images take no prefix, which is what keeps an existing style'sicon-imagevalues working when you convert its stringspriteto the array form. Give the basemap's sheetid: "default"and the shield and POI layers already in the style keep resolving unchanged. - All ids and all URLs must be unique. Duplicates are a validation error (
all the sprites' ids must be unique, but <id> is duplicated), not a last-one-wins merge. - Each URL is still extension-less — MapLibre appends
.json,.png, and the@2xvariants per entry, exactly as for the string form. - From code,
map.addSprite('my-icons', 'https://example.com/sprites/poi')adds a sheet once the style has loaded; a stringspritebecomes the array'sdefaultentry.[3] - ❌
{ "id": "my-icons", "url": "https://example.com/sprites/poi.json" }→ requestspoi.json.json - ❌ Typing
spriteasstringin your own tooling: an array value stringifies to[object Object], and the loader rejects it withInvalid sprite URL "[object Object]", must be absolute. Handle both shapes wherever you read a style'ssprite.
Self-hosted sprites
To avoid third-party dependencies, copy an existing sprite directory (PNG + JSON, plus any @2x files) from a style or tileset provider and host it under your own domain, pointing the style's sprite property at its base URL. Always check the provider's license before republishing and add attribution if required.
Host sprite assets on a static host
Read the complete source ↗