Docs / Setup / React / deck.gl

deck.gl setup

Using deck.gl as a MapConductor map on the web. No key is needed, and the basemap can be any XYZ raster tile set.

PACKAGE
react-for-deckgl
API KEY
None
CSS
Not needed
3D CAMERA
Tilt and bearing

Before you start

Node.js 18 or newer
React 18 or 19
STEP 01

Install

deck.gl (@deck.gl/core, layers and geo-layers 9.x) comes along as a dependency.

terminalnpm
npm install @mapconductor/js-sdk-core @mapconductor/js-sdk-react \
            @mapconductor/react-for-deckgl
STEP 02

Choose a basemap

deck.gl has no map of its own, so the basemap is drawn from XYZ raster tiles. Besides the built-in designs, pass a tile URL template to use your own tiles; put the credit in attributionRules.

designs.tsTypeScript
import { DeckGLDesign } from '@mapconductor/react-for-deckgl';

const gsi = new DeckGLDesign({
  id: 'gsi-standard',
  tileUrl: 'https://cyberjapandata.gsi.go.jp/xyz/std/{z}/{x}/{y}.png',
  tileSize: 256,
  maxZoom: 18,
  attributionRules: [{ attribution: '国土地理院' }],
});

state.mapDesignType = gsi;
CAUTION
The public OpenStreetMap tile servers have a usage policy. For production traffic, serve your own tiles or use a commercial service.
STEP 03

Load it only when needed

Importing @mapconductor/react-for-deckgl loads deck.gl itself. The state and the designs are also available from @mapconductor/react-for-deckgl/state, so the map can be loaded later with lazy(). DeckGLView is just a component that imports DeckGLMapView from the root and passes it the state.

Page.tsxTypeScript · React
import { lazy, Suspense } from 'react';
import { DeckGLDesign, useDeckGLMapViewState } from '@mapconductor/react-for-deckgl/state';

const DeckGLView = lazy(() => import('./DeckGLView'));

export function Page() {
  const state = useDeckGLMapViewState({ mapDesignType: DeckGLDesign.Dark });
  return (
    <Suspense fallback={null}>
      <DeckGLView state={state} />
    </Suspense>
  );
}

VERIFY

What you should see

You are done when the map and the marker appear.

DeckGLMap.tsxTypeScript · React
import { createGeoPoint, createMapCameraPosition, createMarkerState } from '@mapconductor/js-sdk-core';
import { Marker } from '@mapconductor/js-sdk-react';
import { DeckGLDesign, DeckGLMapView, useDeckGLMapViewState } from '@mapconductor/react-for-deckgl';
import { useState } from 'react';

const TOKYO = createGeoPoint({ latitude: 35.6812, longitude: 139.7671 });

export function DeckGLMap() {
  const state = useDeckGLMapViewState({
    mapDesignType: DeckGLDesign.Standard,
    cameraPosition: createMapCameraPosition({ position: TOKYO, zoom: 12 }),
  });
  const [markerState] = useState(() => createMarkerState({ id: 'tokyo', position: TOKYO }));

  return (
    <DeckGLMapView state={state} containerStyle={{ height: 480 }}>
      <Marker state={markerState} />
    </DeckGLMapView>
  );
}

Map designs

DeckGLDesign wraps a tile URL template. To use your own tiles, construct one with new.

DeckGLDesign
Notes
Standard
OpenStreetMap standard tiles, max zoom 19
Satellite
Esri World Imagery
Dark
CARTO dark, max zoom 20
Light
CARTO light, max zoom 20
None
No basemap — for overlays or a vector style on their own

Troubleshooting

It fails on a page that also has Longdo or Mappls

  • deck.gl registers its version on globalThis.deck and throws when a different version is already there. The Longdo SDK brings deck.gl 8.x, and Mappls does the same. Keep them off the same page, and use /state with lazy() so deck.gl loads only when needed.

Place names rotate with the map

  • The basemap is raster tiles, so the text is part of the image. If labels must stay upright, choose a provider that draws vector styles, such as MapLibre.

Rotation and tilt cannot be disabled separately

  • deck.gl's dragRotate covers both, so one cannot be turned off alone. Asking for it leaves both enabled and logs a one-time warning.

Next

Markers, circles, polylines, polygons, ground images and raster layers use the same code as on any other provider. For a vector style, combine the vector tile layer with DeckGLDesign.None.