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:

• Marker images, which define what your markers look like.
• Data sources, which define where on the map your markers will appear.
• Marker approaches, and how to choose the right one for your project.
• Marker methods, which you use to add markers to your map.

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 Mapbox GL JS and the Static Images API and the default marker methods used to create them. You can learn more about default marker methods in marker methods, below.

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.

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.

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.

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.
• 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.

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.

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

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

• Tutorial: Add points to a map with Mapbox Studio
• Mapbox Studio Manual sample workflow documentation

^ Back to all marker methods

Use the Static Images API

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

• Static Images API documentation: Overlay options
• Static Images API documentation: Style parameters
• Tutorial: Using style parameters with the Static Images API

^ Back to all marker methods

Use Mapbox GL JS

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 a default Marker
• Use a symbol layer

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

• Mapbox GL JS API documentation: Marker

^ 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

• Mapbox GL JS API documentation: loadImage, addImage, addSource, addLayer
• Mapbox Style Specification: Symbol layer
• Generic marker images

^ 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 annotations
• Use the Maps SDK with a symbol layer

Use the Maps SDK with annotations

If you are using the Mapbox Maps SDK for Android or iOS, you can use a PointAnnotation to access convenient and performant map annotation methods for mobile and embedded applications. This will add marker annotations on top of a map by adding new elements to the style with runtime styling.

Related resources

• Maps SDK for Android guide: Markers and annotations
• Maps SDK for iOS guide: Markers and annotations

^ Back to all marker methods

Use the Maps SDK with a symbol layer

If you are using the 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 adds marker annotations inside a map by adding new elements to the style with runtime styling.

Related resources

• Maps SDK for Android guide: Work with symbol layers
• Maps SDK for iOS guide: Work with symbol layers
• Mapbox Style Specification: Symbol layer

^ Back to all marker methods

Combining marker methods

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.

^ 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

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

• Mapbox GL JS API documentation: addLayer
• Maps SDK for Android guide: Work with circle layers
• Maps SDK for iOS guide: Work with circle layers
• Mapbox Style Specification: Circle layer

^ Back to all marker methods

Use a heatmap layer

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

• Mapbox GL JS API documentation: addLayer
• Maps SDK for Android guide: Work with heatmap layers
• Maps SDK for iOS guide: Work with heatmap layers
• Mapbox Style Specification: Heatmap layer

^ Back to all marker methods