BasemapLayer

@deck.gl-community/basemap-layers exports a runtime API for loading a MapLibre or Mapbox style document and generating deck.gl sublayers from it.

Recommended example:

• BasemapLayer MapView for validating the standard 2D MapView render path

Installation

yarn add @deck.gl-community/basemap-layers

Main Export

import {BasemapLayer} from '@deck.gl-community/basemap-layers';

BasemapLayer is a CompositeLayer that:

• accepts a style URL or parsed style object
• resolves TileJSON-backed sources
• generates background, fill, line, symbol, and raster sublayers
• supports both flat map rendering and globe rendering

Props

style

Type: string | BasemapStyle | null

The style document to render. Pass either:

• a URL string pointing to a style JSON document
• an in-memory MapLibre/Mapbox style object

mode

Type: 'map' | 'globe'

Controls whether the generated sublayers are optimized for a flat map or a globe. Defaults to 'map'.

loadOptions

Type: BasemapLoadOptions | null

Optional loader configuration used by resolveBasemapStyle. This can include:

• baseUrl for resolving relative URLs in in-memory styles
• fetch for a custom fetch implementation
• fetchOptions to customize network requests

globe

Type: {config?: BasemapGlobeConfig}

Optional globe-specific toggles:

• atmosphere: enable atmosphere overlay helpers
• basemap: enable the main globe basemap geometry
• labels: enable symbol-label rendering on the globe path

Runtime Helpers

getBasemapLayers(options)

Generates the deck.gl sublayers for an already-resolved style definition. Use this when you want the sublayers without creating a BasemapLayer instance.

getGlobeBaseLayers(options)

Convenience wrapper around getBasemapLayers that forces mode: 'globe'.

getGlobeTopLayers(options)

Returns the globe overlay layers that should render after the base globe content.

resolveBasemapStyle(style, loadOptions?)

Loads and normalizes a style document. This resolves:

• remote style JSON URLs
• TileJSON-backed source definitions
• relative tile template URLs

Example

import {Deck, _GlobeView} from '@deck.gl/core';
import {BasemapLayer} from '@deck.gl-community/basemap-layers';
import styleJson from '../../../../website/static/mapstyle/deck-light.json';

new Deck({
  views: new _GlobeView(),
  controller: true,
  layers: [
    new BasemapLayer({
      id: 'earth',
      mode: 'globe',
      style: styleJson,
      globe: {
        config: {
          atmosphere: false,
          basemap: true,
          labels: false
        }
      }
    })
  ]
});

For a flat-map reference implementation that avoids globe-specific behavior, see the BasemapLayer MapView example.