Skip to main content

Base Maps

While deck.gl works independently without any map component, when visualizing geospatial datasets, a base map can offer invaluable context for understanding the overlay layers.

Base Maps Renderers

deck.gl has been designed to work in tandem with popular JavaScript base map providers. Depending on your tech stack, deck.gl's support for a particular base map solution may come with different level of compatibility and limitations.

There are three types of integration between deck.gl and a base map renderer:

Overlaid

The Deck canvas is rendered over the base map as a separate DOM element. Deck's camera and the camera of the base map are synchronized so they pan/zoom together. This is the more robust option since the two libraries manage their renderings independently from each other. It is usually sufficient if the base map is 2D.

Deck as overlay on top of the base map

Interleaved

Deck renders into the WebGL2 context of the base map. This allows for occlusion between deck.gl layers and the base map's labels and/or 3D features. The availability of this option depends on whether the base map solution exposes certain developer APIs, and may subject the user to bugs/limitations associated with such APIs.

Note: Deck cannot render into a WebGL1 context. Check your base map solution for WebGL2 compatibility.

Deck interleaved with base map layers

LibraryPure JSReactOverlaidInterleavedDocs
ArcGIS API for JavaScriptexamplelink
Google Maps JavaScript APIexampleexamplelink
harp.glexample
Leafletexample
Mapbox GL JSexampleexamplelink
MapLibre GL JSexampleexamplelink
OpenLayersexample

It is also important to understand the difference between the JS library that renders the map and the map data provider. For example, you can use Mapbox GL JS with the Mapbox service, but also with any other service that hosts Mapbox Vector Tiles. When using a base map, be sure to follow the terms and conditions, as well as the attribution requirements of both the JS library and the data provider.