Add markers

If you have some point data in GeoJSON format or in a vector tileset, then you are ready to put markers on a map. This guide explains the decisions you need to make to add markers to your map.

In this guide, you'll learn about:

Key terms

It can be helpful to understand key terms related to markers. In Mapbox, a marker is a visual representation of a specific coordinate or point feature on a map.

The capitalized word Marker is reserved for default marker methods of that name, and the corresponding objects they create.

For more detailed definitions, click the terms below or visit the Glossary.

  • annotation: in mobile development, a shape or icon added to a map
  • canvas: in web development, an HTML element used to draw graphics
  • custom image: in Mapbox, an image imported by a user
  • DOM: an object representing the structure and content of a web document
  • icon: in Mapbox, the visual part of a marker
  • marker: an image on a map, representing a location
  • Marker: in Mapbox GL JS, the default Marker method and the object it creates
  • point: a geospatial feature defined by one pair of coordinates
  • source: in Mapbox, any data referenced by a map style layer
  • symbol layer: in Mapbox, a layer that renders icons or text on a map

Marker images

Each Mapbox SDK and API provides a default marker image that is used by its default Marker method. Each also allows you to add and use a custom image instead of the default marker image.

Default marker images

In the table below, you can see the default marker images for each SDK or API and the default marker methods used to create them. You can learn more about default marker methods in marker methods, below.

Mapbox GL JSMaps SDK for AndroidMaps SDK for iOSStatic Images API
No default marker icons in Studio

If you are adding markers for custom data in Mapbox Studio, we recommend that you add a custom icon to your style. Mapbox template styles do not include default marker icons. All the icons included in a template style are assigned to represent existing map features.

Custom marker images

You can use any image as a custom marker image on a Mapbox map, as long as it meets the requirements of the SDK or API used to add it.

If you add a custom image to a map style with Mapbox Studio, it will be available in the sprite associated with that style. If you add custom images to your project programmatically, your SDK will determine how those images are stored in your application.

In the table below, you can see examples of custom images used as markers on Mapbox maps, and the methods used to add custom images to a style on different platforms.

Mapbox GL JSMaps SDK for AndroidMaps SDK for iOSStatic Images API

Generic marker images

Need a generic marker image? You can download these generic marker images to use as custom images in your Mapbox map. The package contains multicolored marker images in two formats:

  • You can use the SVG vector images with Mapbox Studio.
  • You can use the PNG raster images with Mapbox SDKs and APIs.

You can also add these markers to a style in your Mapbox account with this Add generic marker images Mapbox Studio example.

Download ZIP

Create custom icons with Maki

You can use the Maki icon editor to create your own marker images or other images to be used as custom icons. Maki is an open source icon set that includes over 180 unique and customizable images.

Add data

To define the locations where markers will appear on your map, you must add a source containing some point data to your map.

Need to create new data?

You can create a dataset with the Mapbox Studio dataset editor. You can also use free tools like geojson.io or QGIS to draw points on a map, then export your data as GeoJSON. These tools can help you get latitude and longitude coordinates.

If you are adding a single marker to a static, non-interactive map image, you can provide your point data as a single pair of {lon},{lat} coordinates in your API request. Learn more in the Static Images API marker method section, below.

To add multiple markers, or to add markers to interactive web or mobile maps, you generally must provide point data in GeoJSON format or in a vector tileset.

  • You can add data to a map style before runtime by using the Mapbox Studio style editor to add a vector tileset as a source for a layer in a map style.

  • You can add GeoJSON data to a map at runtime by hard-coding the data inline or linking to an API endpoint that serves data as GeoJSON.

  • You can add data from a vector tileset to a map at runtime by providing a link to the tileset, which can be hosted on Mapbox, referenced within in a Mapbox style, or hosted externally.

The specific method you choose to add markers to your map will determine the workflow required to add your data source. Continue to the add markers section to choose a method for adding your markers.

Sample data

If you want some sample point data, you can download the GeoJSON data from our Add points to a web map tutorial, or link to the public Mapbox-hosted vector tileset by using its ID: examples.civir98a801cq2oo6w6mk1aor-9msik. This data includes nine point features representing the locations of parks in Chicago, Illinois.

Add markers

Now that you've learned about marker images and source data, you are ready to combine the two to add a marker to your map.

There are two main approaches for this task:

  1. Adding markers inside a map, which offers performance advantages.
  2. Adding markers on top of a map, which offers styling advantages.

Continue reading to understand the two approaches, so you can reflect on the needs of your application and choose a marker method that best fits your project needs.

Approach #1: Adding markers inside a map

The first approach is to add markers inside a map, where they exist in a symbol layer. In web development, this approach is called the canvas method because it draws markers on the HTML canvas element. In mobile development, this is sometimes called the sources and layers method.

Advantages

  • Highly performant; recommended for maps with over 100 markers.
  • Detailed styling options are available for markers inside symbol layers.
  • Easier to style markers consistently across platforms.
  • Markers are exposed to Mapbox APIs, enabling user interactions.
  • In mobile development, reduces the need to synchronize multiple views.
  • Mapbox Maps SDKs v10 includes wrappers supporting this approach.
  • Mapbox Maps SDKs less than v10 offer plugins supporting a limited version of this approach.
  • Symbol layers can be used in combined marker methods.

Disadvantages

  • Can be more complex to implement than default marker methods that add markers on top of a map.
  • Can be more difficult to change a marker image after it is associated with a marker object.

Methods to add markers inside a mapWebAndroidiOSStatic image
Use Mapbox Studio
Use the Static Images API with style parameters
Use Mapbox GL JS with a symbol layer
Use the Maps SDK with an annotation plugin
Use the Maps SDK with a symbol layer
Use the Maps SDK v10
Beta
Use combined marker methods
Use marker alternatives

Approach #2: Adding markers on top of a map

The second approach is to add markers on top of a map, where each marker exists as an object outside of, and on top of the map. In web development, each marker object is an individual HTMLElement that exists on the DOM. In mobile development, each marker object exists as a view which must be synchronized with the map view.

This approach is sometimes called the Marker method, because some Mapbox SDKs offer a default Marker method that uses this approach to create marker objects.

Advantages

  • Default marker methods can simplify marker implementation.
  • Markers are exposed to Mapbox APIs, enabling user interactions.
  • Adding markers outside the map canvas can offer more styling flexibility and control, including the ability to use CSS to style markers on a web map.
  • Markers on top of a map can be used in combined marker methods.
  • Mapbox GL JS markers can be used in combined marker methods.

Disadvantages

  • Less performant for many markers; not recommended for more than 20 markers.
  • Can make it more difficult to style markers consistently across platforms.
  • Can make marker interactions more complex to synchronize.
  • On Android, SurfaceViews can be hard to synchronize.

Methods to add markers on top of a mapWebAndroidiOSStatic image
Use the Static Images API with overlay options
Use Mapbox GL JS with a default Marker
Use the Maps SDK with a default marker
Use combined marker methods

Other approaches

For a simpler approach, you can use marker alternatives like circle or heatmap layers to visualize point data without markers.

For more advanced use cases, you can combine these two marker approaches to maximize the advantages and minimize the disadvantages of each.

Marker methods

Now that you understand the performance and styling tradeoffs of the two main approaches, you are ready to choose the marker method that best suits the needs of your project. This section describes different methods for adding markers, including platform information, documentation, use cases, and pros and cons for each method.

Use Mapbox Studio

Beginner
WebAndroidiOSStatic image

To add markers to an interactive map without writing any code, you can use Mapbox Studio. If you choose this method, your end product will be a style that you can use with any Mapbox map on any platform. See an example style here. This method adds markers in a symbol layer inside a map.

Related resources

Pros
Cons
Use cases
  • Rapid prototyping
  • Designers collaborating with developers
  • Data sets that do not change or update

^ Back to all marker methods


Use the Static Images API

Beginner
WebAndroidiOSStatic image

When you use the Static Images API, your end product will be a non-interactive raster image of a map that you can use on a webpage, in a mobile application, or for any other purpose. You can use the Static Images API with overlay options or style parameters.

  • If you use overlay options, you will include your point data in your Static Images API request and the API will add markers on top of a map before creating a static image.
  • If you have an existing style layer with markers on it, you can use style parameters in your Static Images API request to add that layer inside a map before creating a static image.

Related resources

Pros
  • API requests can be short, sometimes one line of code
  • Images rendered server-side use minimal client resources
  • Image files are versatile, ideal for primitive devices
  • Customizable map styles and marker overlays
  • Ability to use existing style layers to add or filter data
Cons
  • Static map images are non-interactive
  • Character limits and other API restrictions
Use cases
  • Map image in a mobile push notification
  • Map image in an email receipt
  • Preview image for click-through to an interactive map
  • Map image on a webpage

^ Back to all marker methods


Use Mapbox GL JS

Beginner
Web

When you add markers to a map with Mapbox GL JS, your end product will be an interactive web map with markers that are exposed to the API, available for popups or other interactions. There are two main approaches:

Use Mapbox GL JS with a default Marker

When you use the default Marker with Mapbox GL JS, the API creates Marker objects on top of a map. The default marker image will appear unless you specify a custom marker image. This Marker is sometimes called an HTML marker because it is rendered as an HTMLElement on the DOM.

Related resources

Pros
  • Default marker image is provided
  • Only one line of code needed to create Marker instances
  • You can use a custom marker image
  • See advantages of adding markers on top of a map
Cons
Use cases
  • Rapid prototyping
  • Web maps displaying fewer than 100 points

^ Back to all marker methods


Use Mapbox GL JS with a symbol layer

When you use a symbol layer with Mapbox GL JS, the API draws markers inside a map. This method requires the combined use of loadImage and addImage to add a custom marker image, addSource to add a source, and addLayer to add a symbol layer to the style.

Related resources

Pros
Cons
Use cases
  • Web maps displaying more than 100 points

^ Back to all marker methods


Use the Mapbox Maps SDK

You can use a Mapbox Maps SDK for Android or iOS to add annotations to Mapbox maps in mobile and embedded applications. Click a method below to learn more:

Use the Maps SDK with an annotation plugin

Intermediate
AndroidiOS
Beta

If you are using a compatible version (less than v10) of the Mapbox Maps SDK for Android or iOS, you can use an Annotation Plugin or Extension to access convenient and performant map annotation methods for mobile and embedded applications. These plugins add marker annotations inside a map by adding new elements to the style with runtime styling.

Related resources

Pros
Cons
  • On iOS, cannot add platform native UIViews as markers
  • Plugins obfuscate required boilerplate code
  • Annotation plugins for SDK versions less than v10 offer fewer symbol layer options than the wrappers in v10.
  • See disadvantages of adding markers inside a map
Use cases
  • Mobile and embedded applications

^ Back to all marker methods


Use the Maps SDK with a symbol layer

Advanced
Android
Warning
iOS

If you are using a compatible < v10 version of a Mapbox Maps SDK for Android or iOS, you can use a symbol layer manually to add markers to a map in a mobile or embedded application. This method is easier than, and equally performant as, the wrappers in Mapbox mobile Maps SDK v10 or the Annotation Plugins. This method adds marker annotations inside a map by adding new elements to the style with runtime styling.

Related resources

Pros
Cons
Use cases
  • Mobile and embedded applications

^ Back to all marker methods


Use the Maps SDK with a default marker

Intermediate
AndroidiOS

Mapbox mobile Maps SDKs < v10 provide default marker methods and default marker images which you can replace with custom images. This method adds marker annotations on top of a map.

Related resources

Pros
Cons
Use cases
  • Rapid prototyping
  • Maps displaying fewer than 20 points

^ Back to all marker methods


Use the Maps SDK v10
Beta

Intermediate
AndroidiOS

The Mapbox Maps SDK v10 for iOS and Android includes wrappers that were previously available in annotation plugins. These wrappers are bundled into the SDK to support convenient and performant annotations for Mapbox maps in mobile and embedded applications. These wrappers add marker annotations inside a map by adding new elements to the style with runtime styling.

Related resources

Pros
Cons
Use cases
  • Mobile and embedded applications

^ Back to all marker methods


Combining marker methods

Advanced
WebAndroidiOS

You can combine these methods by using a canvas method to add many points to a map, then using event bindings to add more complex HTMLElement objects. This can be an efficient way to maximize the performance benefits of a symbol or circle layer while also using the styling power of CSS on your HTML markers. This method uses both marker approaches described above.

Pros
Cons
  • Requires more complex architecture
Use cases
  • Data visualization, data journalism, interactives
  • Data sets with more than 100,000 points

^ Back to all marker methods


Marker alternatives

You can visualize point data without icons or markers by using circle or heatmap layers. These layer types are well-suited for visualizing massive data sets including over 100,000 points. They can be combined with methods that add markers on top of a map.

Use a circle layer

Beginner
WebAndroidiOSStatic image

To visualize points on a map with filled circles instead of marker images, you can use a circle layer. If you choose this method, when a client loads your map, it will draw your circles inside the map canvas. This method uses the canvas method to add circles inside a map.

Related resources

Pros
  • Performant method for visualizing millions of points
  • No marker image required
  • Circle paint properties are ideal for data-driven styling
  • Supports built-in point clustering
  • Circles are exposed to the API, enabling user interaction
  • Can be used in combined marker methods
  • See advantages of adding markers inside a map
Cons
Use cases
  • Data visualization, data journalism, interactives
  • Data sets with more than 100,000 points
  • Rapid prototyping

^ Back to all marker methods


Use a heatmap layer

Beginner
WebAndroidiOSStatic image

To visualize points on a map with a heatmap, you can use a heatmap layer. If you choose this method, when a client loads your map, it will draw your circles inside the map canvas. This method uses the canvas method to render a heatmap inside a map.

Related resources

Pros
Cons
Use cases
  • Data visualization, data journalism, interactives
  • Data sets with more than 100,000 points

^ Back to all marker methods