A lot of the examples always load the icon image like this (For example here: https://www.mapbox.com/mapbox-gl-js/example/geojson-markers/):

    "id": "markers",
    "type": "symbol",
    "source": "markers",
    "layout": {
        "icon-image": "{marker-symbol}-15",
        "text-field": "{title}",
        "text-font": ["Open Sans Semibold", "Arial Unicode MS Bold"],
        "text-offset": [0, 0.6],
        "text-anchor": "top"

Where is this icon stored and how can I link to a local png or svg? Or how can I put my own markersinto source? The example is not very well documented.

  • Did you check the 'style reference' section of the API docs?
    – Tangnar
    Feb 3 '16 at 14:20
  • 3
    It is not very well explained in my opinion. Would love to see a well explained working example. Feb 3 '16 at 16:04

If you follow the examples, you only get the sprites that load with your particular style's sprite sheet, which is NOT NECESSARILY a 1 to 1 match with any other style.

ex: emerald-v8 has NO "icon-image":"harbor-15" like the example that uses streets-v8.

To see the list of available sprites from corresponding styles: https://github.com/mapbox/mapbox-gl-styles/tree/master/sprites

I can choose the "harbor" icon from their emerald-v8 repository like so:

    "id": "pointclick",
    type: 'symbol',
    source: 'pointclick',
    "layout": {
        "icon-image": "harbor_icon",
    "paint": {}

Here is the resource that helped me pull it all together, and it explains how to create your own icons: https://www.mapbox.com/help/custom-markers/#locate-mapbox-styles-images


Basically, to add one of your own icons, go into Mapbox studio, create your own style, or edit one of theirs. Simply add one of your own SVGs, then that icon will become available to you into your custom sprite sheet.enter image description here


You can also use external/generated icons as icon-image if you use map.loadImage() and map.addImage() first.


Add an icon to the map

Add a generated icon to the map


As it is said in sprite docs: Pass "sprite": "https://link" to your style, where link is link to json genereted with spritezero-cli. spritezero-cli generated png sprite from list of your icons in svg format. That you can use icons in symbol layers as 'icon-image'.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.