Inconsistent layer rendering order
When using the Globe projection at low zoom levels or adding a Terrain source to enable 3D terrain, some layers of a Mapbox map style may appear out of their expected order.
Typically, layers are displayed in the order of their declaration, with later layers appearing on top of earlier ones. This applies to layers originating from a map style or added at runtime. When a style includes an import such as the Mapbox Standard Style, additional layers can be placed in a slot, which follows the same ordering rules—earlier layers in a slot render below later layers. Layers not associated with slots appear above the entire map while maintaining their relative order.
This troubleshooting guide explains why the layer re-ordering occurs and offers some potential workarounds.
Why does layer re-ordering happen?
Using the globe projection at low zoom levels or using a terrain source for 3D terrain rendering can cause the renderer to rearrange the rendering order of certain layer types due to draping. In these cases, the renderer optimizes performance by batching multiple layers together, which may cause layer rearrangements. Layers draped over the globe and terrain, including fill, line, background, hillshade, and raster, are rendered below symbols, regardless of slot placement or the absence of a designated slot.
Layer re-ordering when using Globe Projection
When using the Globe projection at low zoom levels, the curvature of the earth requires draping for the layer types specified above.
In the example below, there are 2 custom sources & layers added to the map. A polygon source is rendered as a red fill layer and is added to the top slot in the Mapbox Standard style. A second layer of a point source is rendered as a blue circle layer and is added to the middle slot in the Mapbox Standard style. When the map is rendered with a mercator projection, the fill layer appears above the circle layer as expected. But when the map is rendered with a globe projection, the fill layer must be draped over the globe and is rendered below the circle layer due to the optimized layer rendering of the SDK.
In the example below, you can see that the fill layer is rendered below the circle layer when the map is rendered with a globe projection. As this occurs only a low zoom levels, if you zoom in, you will see that the fill layer is rendered above the circle layer as expected as the globe projection is no longer required at higher zoom levels.
Layer re-ordering when 3D terrain is enabled
When 3D terrain is enabled, draping is also required for the specified layer types. In the example below, similar sources & layers have been added to the map. The red polygon layer is placed in the top slot and the blue circle layer is placed in the middle slot. When the map is rendered with a terrain source, the fill layer is rendered below the circle layer, and symbol layer for POI's, places & transit labels due to draping and the optimization behavior of the SDK.
Working around layer re-ordering
If you have issues with layer rendering order due to the globe projection or terrain source, there are few workarounds you can consider:
- Use
line-z-offsetforlinelayers: If you are usinglinelayers, you can use theline-z-offsetproperty to raise the layer above the terrain, preventing it from being re-ordered below other layers. This is a workaround that allows you to keep the desired rendering order while still benefiting from terrain draping. See more details in the section below. - Disable Terrain: If your application does not require 3D terrain rendering, you can disable the terrain source in your map style. This will prevent the SDK from reordering layers due to terrain draping.
- Change Projection: If your application does not require the globe projection, you can switch to the Mercator projection. This will make sure that layers are rendered in the order they are declared, without the need for draping.
- Adjust Layer Types: If possible, consider using layer types that are not affected by the reordering behavior. For example, using
symbollayers instead offillorlinelayers may help keep the desired rendering order.
Using line-z-offset to maintain rendering order for line layers
If you need to maintain the rendering order of line layers types that are being affected by globe projection or terrain sources, it is possible to use a line-z-offset in your style configuration. This property specifies a vertical offset for the layer, raising the layer off the surface of the map, which stops re-ordering from the optimized batch layering, but still maintains draping over the terrain.
This work around is not available for other layer types.
In the example above the purple line layer has the following style configuration:
mapRef.current.addLayer({
'id': 'purple-line',
'source': 'lines',
'type': 'line',
'paint': {
'line-color': 'purple',
'line-width': 25,
},
'layout': {
'line-elevation-reference': 'ground',
'line-z-offset': 5,
}
'slot': 'top'
});
The layout property line-z-offset is used to raise the layer above the terrain, preventing it from being re-ordered below the yellow circle layer. The value of the line-elevation-reference property is ground, which means that the line will be rendered at a height above the ground level, and the line-z-offset value is 5, which raises the line by 5 meters. The line-elevation-reference is a required property when using line-z-offset.