Skip to main content

This module makes it easy to use as native layers and controls in the Mapbox GL JS ecosystem.

  • It allows to be used with other mapbox-gl controls such as NavigationControl, GeolocateControl and mapbox-gl-geocoder.
  • You may choose to interleave layers with the base map layers, such as drawing behind map labels, z-occlusion between 3D objects and Mapbox buildings, etc.


Include the Standalone Bundle

<script src="^8.1.0/dist.min.js"></script>
<script src=''></script>
<script type="text/javascript">
const {MapboxOverlay} = deck;

Install from NPM

npm install
import {MapboxOverlay} from '';

Use Cases

One should note that this module is not required to use mapbox-gl as a base map for When you use this module, Mapbox is the root element and is the child, with Mapbox handling all user inputs. Some of's features are therefore unavailable due to limitations of mapbox-gl's API, see limitations below. If you just want the base map as a back drop, and do not need mapbox-gl's UI controls or mixing deck and Mapbox layers, it is recommended that you use as the root element. Visit the mapbox base map developer guide for examples of each option.

It may be easier to understand the concepts of the module if you are already a mapbox-gl developer.

Mixing layers and Mapbox layers

One major use case for interleaving and Mapbox is that some important information in the Mapbox map could be hidden by a visualization layer, and controlling opacity is not enough. A typical example of this is labels and roads, where it is desirable to have a visualization layer render on top of the Mapbox geography, but where one might still want to see e.g. labels and/or roads. Alternatively, the visualization should cover the ground, but not the roads and labels.

To inject a deck layer into the Mapbox stack, either:

Mapbox provides an example of finding the first label layer. For more sophisticated injection point lookups, refer to Mapbox' documentation on the format of Mapbox style layers, see Mapbox Style Spec.

In some cases, the application wants to add a 3D layer (e.g. ArcLayer, HexagonLayer, GeoJsonLayer) on top of a Mapbox basemap, while seamlessly blend into the z-buffer. This will interleave the useful visualization layers from both the and Mapbox layer catalogs. In this case, a beforeId is not needed.

Using mapbox-gl controls with

The Mapbox ecosystem offers many well-designed controls, from the basic functionalities of NavigationControl, Popup and GeolocateControl, to vendor-service-bound UI implementations such as mapbox-gl-geocoder and mapbox-gl-directions. These libraries require that the Mapbox Map holds the source of truth of the camera state, instead of the normal state management by Deck. When you use the MapboxLayer or MapboxOverlay classes from this module, plays nice with all the mapbox-gl peripherals.


  • When using's multi-view system, only one of the views can match the base map and receive interaction. See using MapboxOverlay with multi-views for details.
  • When using as Mapbox layers or controls, Deck only receives a subset of user inputs delegated by Map. Therefore, certain interactive callbacks like onDrag, onInteractionStateChange are not available.
  • WebGL2 based features, such as attribute transitions and GPU accelerated aggregation layers cannot be used.
  • Mapbox/Maplibre's terrain features are partially supported. When a terrain is used, the camera of and the base map should synchronize, however the data with z=0 are rendered at the sea level and not aligned with the terrain surface.