Choose between Markers and Layers for point data in Mapbox GL JS
Mapbox GL JS provides two distinct approaches to symbolizing point data on the map, markers and layers. Markers are HTML elements that appear "on top" of the map on a webpage. As the user interacts with the map, Mapbox GL JS determines the correct placement of each element, updating their positions in real-time. Markers do not require a corresponding source from the map.
Layers, (specifically circle and symbol layers) are rendered as part of the map itself. They can be positioned above or below other map layers, and styled according to the Style Specification.
This guide explains the differences between these two approaches and when to use one versus the other.
Markers
Markers are HTML elements that represent a point, but are not a part of the map's style.
Each marker added to a Mapbox GL JS map requires a separate call to create a new mapboxgl.Marker(). Since markers do not require adding a data source to the map, they are simpler to use. Only a latitude and longitude are require to display a default marker on the map. The default markers can be further customized with colors, sizes, and popup functionality.
Example: Add a default marker to a web map
Marker objects live on their own and are not implicitly tied to data. This also means you don't need to worry as much about having data in GeoJSON format to use them, which might make them simpler to implement depending on your environment. Markers can be stored as variables and can be updated after they are created. See our “Animate a Marker” tutorial for an example of how to update a Marker object.
Because markers are HTML elements positioned above the map container, you can use any element, image, or SVG to customize them.
Tutorial: Add custom markers in Mapbox GL JS
Layers
Layers are rule-based visualizations of a data source in a map's style. The circle or symbol types are typically used to display point data.
Using layers to display points requires a corresponding source of point data to exist in the map's style. Point data sources can be vector tiles you prepare ahead of time or GeoJSON data added at runtime.
A layer of type circle renders a circle over the point, which can by styled to change things like color, stroke, and opacity based on the underlying data. A layer of type symbol can either display a sprite/image on the map, or can be used to display text at the point's location.
Layers are defined according to the Style Specification which provides a high level of control over their display and placement. Layers can also contain rules for data-driven styling, for example using a different color or icon based on a point feature's properties.
Because they live as part of the map's style, updating existing layers requires calls to setPaintProperty and setLayoutProperty. The learning curve can be higher, but changes are applied to the layer collectively, meaning less code is required than for making broad changes to a collection of Markers.
Dataset Size
The size of the point dataset you want to display on your map can play a role in choosing between Markers or Layers.
Markers require the creation and management of a new HTML element, and adding hundreds of Markers to a Mapbox GL Map can cause a web browser to become unresponsive or sluggish.
Conversely, displaying the same dataset of hundreds of points in a circle or symbol layer is not likely to cause a noticeable performance impact as they are more efficiently rendered on the Map's WebGL canvas.
Once your dataset gets into the thousands of points, you may find efficiency gains by using a vector tileset to serve the data, meaning only the data within the current map viewport is loaded into the browser. In any case, once you make the move to vector tiles Markers are no longer an option.
Comparison
This chart highlights selected capabilities of Markers and Layers for displaying point data in Mapbox GL JS.
| Capability | Markers | Layers |
|---|---|---|
| Can display local data in any format | ||
| Can display local geojson data | ||
| Can display data from vector tiles | ||
| Requires adding a source to the map | ||
| Can be styled with CSS | ||
| Styled with the Style Specification | ||
| Suitable for displaying dozens of points | ||
| Suitable for displaying hundreds of points | ||
| Created and updated individually | ||
| Created and updated collectively |