Skip to main content

MapboxOverlay

MapboxOverlay is an implementation of Mapbox GL JS's IControl API. When adding a MapboxOverlay control to an mapbox map, deck.gl layers are rendered in synchronization with the base map layers. This control supports both overlaid and interleaved rendering modes.

Example​

import {MapboxOverlay} from '@deck.gl/mapbox';
import {ScatterplotLayer} from '@deck.gl/layers';
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/light-v9',
  accessToken: '<mapbox_access_token>',
  center: [0.45, 51.47],
  zoom: 11
});

map.once('load', () => {
  const deckOverlay = new MapboxOverlay({
    interleaved: true,
    layers: [
      new ScatterplotLayer({
        id: 'deckgl-circle',
        data: [
          {position: [0.45, 51.47]}
        ],
        getPosition: d => d.position,
        getFillColor: [255, 0, 0, 100],
        getRadius: 1000,
        beforeId: 'waterway-label' // In interleaved mode render the layer under map labels. Replace with `slot: 'bottom'` if using Mapbox v3 Standard Style.
      })
    ]
  });

  map.addControl(deckOverlay);
});

Constructor​

import {MapboxOverlay} from '@deck.gl/mapbox';
import type {MapboxOverlayProps} from '@deck.gl/mapbox';

new MapboxOverlay(props: MapboxOverlayProps);

MapboxOverlay accepts the same props as the Deck class, with the following exceptions:

  • views - multi-view support is limited. There is only one MapView that can synchronize with the base map. See the using with multi-views section for details.
  • parent / canvas / device - context creation is managed internally.
  • viewState / initialViewState - camera state is managed internally.
  • controller - always disabled (to use Mapbox's interaction handlers).

The constructor additionally accepts the following options:

  • interleaved (boolean) - If false, a dedicated deck.gl canvas is added on top of the base map. If true, deck.gl layers are inserted into mapbox-gl's layer stack, and share the same WebGL2RenderingContext as the base map. Default is false. Note that interleaving with basemaps such as mapbox-gl-js v1 that only support WebGL 1 is not supported, see compatibility.

When using interleaved: true, deck.gl layers are grouped by their beforeId or slot prop and rendered in batches. You may control the ordering of layers in the Mapbox/MapLibre stack by optionally adding a beforeId prop to a layer. If multiple deck.gl layers have the same beforeId, they are rendered together in the order that is passed into the layers array, enabling cross-layer extension handling (e.g. MaskExtension, CollisionFilterExtension). If used with Mapbox v3 Standard Style, supply a slot prop to layers instead.

Note that extensions which require layers to share a rendering context (such as MaskExtension and CollisionFilterExtension) only work between layers within the same group. Ensure that layers using these extensions share the same beforeId or slot value.

Methods​

setProps​
const overlay = new MapboxOverlay({
  interleaved: true,
  layers: []
});

map.addControl(overlay);

// Update layers
overlay.setProps({
  layers: [new ScatterplotLayer({...})]
})

Updates (partial) props of the underlying Deck instance. See Deck.setProps.

pickObject​

See Deck.pickObject.

pickObjects​

See Deck.pickObjects.

pickMultipleObjects​

See Deck.pickMultipleObjects.

finalize​

Removes the control and deletes all resources.

getCanvas​

See Deck.getCanvas. When using interleaved: true, returns the base map's canvas.

Remarks​

Multi-view usage​

When using MapboxOverlay with multiple views passed to the views prop, only one of the views can match the base map and receive interaction.

With that said, it is still possible to take advantage of deck's multi-view system and render a mapbox base map onto any one MapView of your choice by setting the views array and a layerFilter callback.

View ID Conventions:

  • MapboxOverlay internally uses a MapView with the id "mapbox" to synchronize with the base map's camera.
  • You can reference this view id in your layerFilter to control which layers render on the main map.
  • When providing custom views, you do not need to explicitly include a view with id "mapbox" - it will be automatically injected if not present.
  • If you want to customize the mapbox-synchronized view (e.g., to control draw order with other custom views), you can explicitly define a MapView({id: 'mapbox'}) in your views array.
import {MapboxOverlay} from '@deck.gl/mapbox';
import {Deck, MapView, OrthographicView} from '@deck.gl/core';
import {ScatterplotLayer} from '@deck.gl/layers';

const map = new mapboxgl.Map({...});

const overlay = new MapboxOverlay({
  views: [
    // This view will be synchronized with the base map
    new MapView({id: 'mapbox'}),
    // This view will not be interactive
    new OrthographicView({id: 'widget'})
  ],
  layerFilter: ({layer, viewport}) => {
    const shouldDrawInWidget = layer.id.startsWith('widget');
    if (viewport.id === 'widget') return shouldDrawInWidget;
    return !shouldDrawInWidget;
  },
  layers: [
    new ScatterplotLayer({
      id: 'my-scatterplot',
      data: [
        {position: [-74.5, 40], size: 100}
      ],
      getPosition: d => d.position,
      getRadius: d => d.size,
      getFillColor: [255, 0, 0]
    }),
    new ScatterplotLayer({
      id: 'widget-scatterplot',
      data: [
        {position: [0, 0], size: 100}
      ],
      getPosition: d => d.position,
      getRadius: d => d.size,
      getFillColor: [255, 0, 0]
    })
  ]
});

map.addControl(overlay);