Skip to main content

This module integrates into the Mapbox GL JS API-compatible ecosystem.

  • It synchronizes a MapView with the mapbox-gl camera.
  • It allows to be used with mapbox-gl controls and plugins such as NavigationControl, GeolocateControl and mapbox-gl-geocoder.
  • It adds the option to interleave layers with the base map layers, such as drawing behind map labels, z-occlusion between 3D objects and Mapbox buildings, etc.

This module may be used in the React, Pure JS, and Scripting Environments. Visit the mapbox base map developer guide for examples of each option.

When you use this module, Mapbox is the root HTML 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.

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

This module is compatible with Mapbox GL JS forks. Known exceptions will be clearly marked. For more, see Compatibility with Mapbox GL JS forks


Include the Standalone Bundle

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

Install from NPM

npm install
import {MapboxOverlay} from '';

Camera Syncronization between and Mapbox

This module keeps a MapView in sync with the mapbox-gl camera so that the base map and deck layers are always geospactially aligned. Some Deck props, such as viewState, are ignored or have different behavior. See MapboxOverlay constructor notes. Also, some camera features are unable to be fully synchronized due to mapbox-gl API limitations, see limitations.

Using mapbox-gl controls and plugins 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 MapboxOverlay classes from this module, plays nice with all the mapbox-gl peripherals.

Mixing layers and Mapbox layers

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 add an interleaved: true props to the MapboxOverlay control and add a beforeId prop to any layer passed to the MapboxOverlay control.

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.

Interleaved Renderer Compatibility

The following table details renderer support across different versions of mapbox-gl and maplibre-gl. See base map renderers to learn about the differences between overlaid and interleaved renderers.

LibraryOverlaid (default)Interleaved
mapbox-gl-js (before v2.13)
mapbox-gl-js v2.13+✓ with useWebGl2: true
mapbox-gl-js v3+
maplibre-gl-js (before v3)
maplibre-gl-js v3+✓*

*will fallback to WebGL1 if WebGL2 is not available

Alternative Mapbox Integrations

If you're using in a React or Scripting environment, you just want the base map as a back drop, and do not need mapbox-gl's UI controls or need to mix and Mapbox layers, it is recommended that you do not use this module and instead use as the root HTML element. Visit Using as the root HTML element for an example.


  • 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.
  • 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.
  • Only Mercator projection is supported. Mapbox adaptive projection is not supported as their API doesn't expose the projection used.
  • The position property in viewState has no equivalent in mapbox-gl.