The term icon can have different meanings depending on the context of its use. On a map, an icon is generally a visual representation of a point in space. In the context of markers used in Mapbox products, an icon is the visual part of a marker, which gets paired with geospatial data to represent a feature on a map.

In Mapbox, icons appear most often inside symbol layers, but they can also be added on top of a map object using platform-native methods. An icon can be a theme image, a custom image, a Maki icon, or a generated icon.

  • Theme images are icon and pattern images provided in Mapbox template styles to style map features. Each style stores these images in its sprite, which is managed by the Mapbox Studio style editor. Theme images are built into Mapbox template styles. Since they are used to represent existing features in a style, theme images are not recommended for visualizing custom point data.

  • Custom images are images that you add to a map style. Custom images can be used as an icon-image or a fill-pattern with a style layer. Custom images added with the Mapbox Studio style editor are available in the style's sprite when the style loads. Custom images added at runtime with a Mapbox SDK or API are available in the style's sprite only after the image has been successfully loaded and added to the style. Custom images are recommended for visualizing custom data.

  • Maki icons are images in the open source Maki icon set made for map designers. Some Mapbox-owned vector tilesets include a maki field to make it easier for developers to use Maki icons in map.

  • Generated icons are images created with code, as distinct from icons that reference SVG or PNG image files. Generated icons can be used as a fallback for missing images to make an app more robust.

Related resources:

Related examples: