How can I use custom icons on my map?

[antonpirker]

I have created a custom map style using mapmaker.maptoolkit.org and now I want to have custom icons for churches, peaks, water sources and so on.

How can I do this?

[yhay81]

MapMaker can change the built-in icon styling, but it does not currently upload and host a custom sprite for the style. There are two practical ways to add your own icons after exporting the style.

1. Add the images in MapLibre GL JS (simplest)

Load each PNG after the style has loaded, register it with addImage, then change the POI symbol layers' icon-image expression.

map.on('style.load', async () => {
  const custom = {
    church: '/icons/church.png',
    peak: '/icons/peak.png',
    water: '/icons/water.png'
  };

  for (const [id, url] of Object.entries(custom)) {
    const image = await map.loadImage(url);
    if (!map.hasImage(id)) map.addImage(id, image.data);
  }

  const iconForType = [
    'match', ['get', 'type'],
    'YOUR_CHURCH_TYPE', 'church',
    'peak', 'peak',
    'drinking_water', 'water',
    // Preserve the Maptoolkit icon for every other POI:
    ['concat', 'sdf:', ['get', 'type']]
  ];

  for (const layer of map.getStyle().layers) {
    if (layer.type === 'symbol' &&
        layer['source-layer'] === 'poi_label' &&
        layer.id.startsWith('poi_label_')) {
      map.setLayoutProperty(layer.id, 'icon-image', iconForType);
      map.setLayoutProperty(layer.id, 'icon-optional', true);
    }
  }
});

Replace YOUR_CHURCH_TYPE with the actual type property in the vector feature. The existing Maptoolkit styles are data-driven: their ordinary POI layers use ["concat", "sdf:", ["get", "type"]]. Peaks are in separate poi_label_peak_rank_* layers and currently have text but no icon-image, which is why the loop includes all poi_label_* symbol layers.

You can inspect the exact properties at a clicked location with map.queryRenderedFeatures(e.point).

2. Put the icons in the exported style (portable/self-hosted)

Generate a MapLibre sprite (.png + .json, and preferably @2x variants) from your SVG/PNG files, host it with CORS enabled, and append it to the exported style's existing sprite array:

"sprite": [
  { "id": "sdf",    "url": "https://icons.maptoolkit.org/sprite" },
  { "id": "nature", "url": "https://icons.maptoolkit.org/nature~..." },
  { "id": "water",  "url": "https://icons.maptoolkit.org/water~..." },
  { "id": "mine",   "url": "https://example.com/sprites/my-icons" }
]

Then use names such as mine:church and mine:peak in the same icon-image match expression. Keep the existing sprite entries, otherwise the other basemap symbols disappear. If you want icon-color and icon-halo-color to recolor your artwork, generate SDF icons; a normal multicolor PNG keeps its baked-in colors.

References: the repository's hiking style shows the current sprite and POI-layer structure; MapLibre documents multiple sprite sources and the runtime loadImage/addImage approach.