> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/help/ja/llms.txt)

# Inconsistent layer rendering order

When using the Globe [projection](https://docs.mapbox.com/help/ja/glossary/projection/) at low zoom levels or adding a [Terrain source](https://docs.mapbox.com/style-spec/reference/terrain/#source) to enable 3D terrain, some layers of a Mapbox map style may appear out of their expected order.

Typically, [layers](https://docs.mapbox.com/style-spec/reference/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](https://docs.mapbox.com/map-styles/standard/guides/), 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](https://docs.mapbox.com/help/ja/glossary/projection/) at low zoom levels or using a [terrain source](https://docs.mapbox.com/style-spec/reference/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`](https://docs.mapbox.com/style-spec/reference/layers/#fill), [`line`](https://docs.mapbox.com/style-spec/reference/layers/#line), [`background`](https://docs.mapbox.com/style-spec/reference/layers/#background), [`hillshade`](https://docs.mapbox.com/style-spec/reference/layers/#hillshade), and [`raster`](https://docs.mapbox.com/style-spec/reference/layers/#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.

> **Note: Globe projection re-ordering occurs at low zoom levels only**
> 
> 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-offset` for `line` layers:** If you are using `line` layers, you can use the `line-z-offset` property 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 `symbol` layers instead of `fill` or `line` layers 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:

```js
mapRef.current.addLayer({
  'id': 'purple-line',
  'source': 'lines',
  'type': 'line',
  'paint': {
      'line-color': 'purple',
      'line-width': 25,

  },
  // highlight-start
  'layout': {
      'line-elevation-reference': 'ground',
      'line-z-offset': 5,
  }
  // highlight-end
 'slot': 'top' 
});
```

The `layout` property [`line-z-offset`](https://docs.mapbox.com/style-spec/reference/layers/#layout-line-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`](https://docs.mapbox.com/mapbox-gl-js/style-spec/expressions/#line-elevation-reference) is a required property when using `line-z-offset`.