React Map GL Components

Drop-in components for using Esri services with react-map-gl. Works with both MapLibre GL and Mapbox GL.

Components

All components share these common props:

Prop	Type	Description
id	string	Required Unique layer ID
sourceId	string	Custom source ID (defaults to esri-<kind>-<id>, e.g. esri-dynamic-census)
beforeId	string	Insert layer before this layer ID
visible	boolean	Layer visibility
token	string	ArcGIS token (sent as the token request parameter)
apiKey	string	ArcGIS Location Platform API key (sent as the token parameter)
authentication	IAuthenticationManager | string	ArcGIS REST JS auth manager (preferred for OAuth/user sign-in)
getAttributionFromService	boolean	Whether to fetch attribution from the service (default true)
requestParams	Record<string, unknown>	Extra params merged into every service request
proxy	string | boolean	Deprecated — no longer applied
fetchOptions	RequestInit	Deprecated — no longer forwarded to requests

Requests run on ArcGIS REST JS; see the Authentication guide.

Authenticated services

Use token (or apiKey) on any layer component to access secured services:

<EsriDynamicLayer
  id="secured"
  url="https://your-server/arcgis/rest/services/Secure/MapServer"
  token="YOUR_TOKEN"
/>

EsriVectorBasemapLayer needs a token or an apiKey (see below).

Every layer component also accepts an ArcGIS portal item id in place of its url — see the Portal Items guide.

EsriDynamicLayer

Renders an Esri Dynamic Map Service as a raster layer.

Prop	Type	Default	Description
url	string		Required MapService URL
layers	number[] | number | false		Layer IDs to show
layerDefs	Record<string, string> | false		SQL filters per layer
format	string		Image format
dpi	number		Output DPI
transparent	boolean		Transparent background

import { EsriDynamicLayer } from 'esri-gl/react-map-gl';

<Map>
  <EsriDynamicLayer
    id="census"
    url="https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer"
    layers={[2, 3]}
    layerDefs={{ 2: "STATE_NAME='California'" }}
  />
</Map>

EsriTiledLayer

Renders an Esri Tiled Map Service as a raster layer.

Prop	Type	Description
url	string	Required Tiled MapService URL

import { EsriTiledLayer } from 'esri-gl/react-map-gl';

<Map>
  <EsriTiledLayer
    id="topo"
    url="https://services.arcgisonline.com/arcgis/rest/services/World_Topo_Map/MapServer"
  />
</Map>

EsriImageLayer

Renders an Esri Image Service as a raster layer.

Prop	Type	Description
url	string	Required ImageService URL
renderingRule	Record<string, unknown> | false	Server-side rendering rule
mosaicRule	Record<string, unknown> | false	Mosaic rule for image selection
format	string	Image format

import { EsriImageLayer } from 'esri-gl/react-map-gl';

<Map>
  <EsriImageLayer
    id="landcover"
    url="https://sampleserver6.arcgisonline.com/arcgis/rest/services/NLCDLandCover/ImageServer"
  />
</Map>

EsriFeatureLayer

Renders an Esri Feature Service as a GeoJSON vector layer.

Prop	Type	Default	Description
url	string		Required Feature layer URL
where	string		SQL WHERE filter
outFields	string | string[]		Fields to include
type	'fill' | 'circle' | 'line' | 'symbol' | 'heatmap'	'fill'	Layer type added for the source
paint	Record<string, unknown>		MapLibre paint properties
layout	Record<string, unknown>		MapLibre layout properties

import { EsriFeatureLayer } from 'esri-gl/react-map-gl';

<Map>
  <EsriFeatureLayer
    id="states"
    url="https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3"
    where="POP2000 > 5000000"
    outFields={['STATE_NAME', 'POP2000']}
    paint={{ 'fill-color': '#0080ff', 'fill-opacity': 0.4 }}
  />
</Map>

EsriVectorTileLayer

Renders an Esri Vector Tile Service. The service handles layer creation internally.

Prop	Type	Description
url	string	Required Vector Tile Service URL

import { EsriVectorTileLayer } from 'esri-gl/react-map-gl';

<Map>
  <EsriVectorTileLayer
    id="basemap-vtiles"
    url="https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer"
  />
</Map>

EsriVectorBasemapLayer

Applies an Esri Vector Basemap Style to the map by calling setStyle on it. Note: this replaces the entire map style rather than adding a layer, so any layers other components added are dropped when it mounts.

Prop	Type	Description
basemapEnum	string	Required Basemap style (e.g., 'arcgis/streets', 'arcgis/navigation')
token	string	OAuth / user token (v2 host). Provide token or apiKey.
apiKey	string	ArcGIS Location Platform API key (v1 host). Provide token or apiKey.
language	string	Locale for the basemap labels
worldview	string	Worldview to render disputed boundaries for

import { EsriVectorBasemapLayer } from 'esri-gl/react-map-gl';

<Map>
  <EsriVectorBasemapLayer
    id="basemap"
    basemapEnum="arcgis/navigation"
    token="YOUR_TOKEN"
  />
</Map>

EsriPortalLayer

Deprecated

When you know the service type, pass the item id as the url of the matching layer component (e.g. <EsriDynamicLayer url={itemId} />). Use EsriPortalLayer only when the type must be auto-detected from the item.

Resolves an ArcGIS portal item id to the matching service and adds a renderer-appropriate layer for it — raster for Dynamic/Tiled/Image services, the service's default style for Feature and Vector Tile services.

Prop	Type	Description
itemId	string	Required ArcGIS portal item id to resolve
layerId	number	For multi-layer Feature Services, which sublayer to load (default 0)
portal	string	Portal sharing REST URL (defaults to ArcGIS Online)
onResolve	(result: PortalServiceResult) => void	Called once the item resolves, with the service/kind/url/title
token / apiKey / authentication		Standard auth options

import { EsriPortalLayer } from 'esri-gl/react-map-gl';

<Map>
  <EsriPortalLayer
    id="portal-item"
    itemId="a1b2c3d4e5f6"
    token="YOUR_TOKEN"
    onResolve={({ kind, title }) => console.log(`Loaded ${kind}: ${title}`)}
  />
</Map>

See the Portal Items guide for how item types map to services.

Integration Hooks

These hooks provide access to the underlying map instance and pre-configured service hooks for react-map-gl applications.

useEsriMaplibreLayer

Hook for using Esri services with MapLibre GL via react-map-gl.

Returns:

Property	Type	Description
map	Map | undefined	The MapLibre GL map instance (undefined until the map ref is set)
useDynamicMapService	function	Pre-configured hook
useTiledMapService	function	Pre-configured hook
useImageService	function	Pre-configured hook
useVectorTileService	function	Pre-configured hook
useFeatureService	function	Pre-configured hook

import { useEsriMaplibreLayer } from 'esri-gl/react-map-gl';

function MyLayer() {
  const { map, useDynamicMapService } = useEsriMaplibreLayer();
  const { service } = useDynamicMapService({
    sourceId: 'census',
    map,
    options: { url: 'https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer' },
  });
  return null;
}

useEsriMapboxLayer

Hook for using Esri services with Mapbox GL via react-map-gl. Same API as useEsriMaplibreLayer but uses the Mapbox provider.

Returns:

Property	Type	Description
map	Map | undefined	The Mapbox GL map instance (undefined until the map ref is set)
useDynamicMapService	function	Pre-configured hook
useTiledMapService	function	Pre-configured hook
useImageService	function	Pre-configured hook
useVectorTileService	function	Pre-configured hook
useFeatureService	function	Pre-configured hook

import { useEsriMapboxLayer } from 'esri-gl/react-map-gl';

function MyLayer() {
  const { map, useDynamicMapService } = useEsriMapboxLayer();
  const { service } = useDynamicMapService({
    sourceId: 'census',
    map,
    options: { url: 'https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer' },
  });
  return null;
}