React Hooks

React hooks for managing Esri service lifecycle and running spatial tasks. All hooks handle loading state, error handling, and cleanup automatically.

Service Hooks

These hooks create and manage Esri service instances tied to a map. They all return { service, loading, error, reload }.

useEsriService

Base hook for managing any Esri service lifecycle. Used internally by all other service hooks.

Parameter	Type	Description
createService	(map: Map) => T	Factory function to create a service instance
map	Map | null	MapLibre GL or Mapbox GL map instance
deps	ReadonlyArray<unknown>	Optional. Values that rebuild the service (and its source) when they change — the hook otherwise only rebuilds when map changes

Returns: UseEsriServiceResult<T>

Property	Type	Description
service	T | null	The service instance
loading	boolean	Whether the service is initializing
error	Error | null	Any error during creation
reload	() => void	Recreate the service

const { service, loading, error } = useEsriService(
  (map) => new DynamicMapService('my-source', map, { url: serviceUrl }),
  map,
  [serviceUrl] // rebuild when the url changes
);

useDynamicMapService

Hook for DynamicMapService. Automatically updates layers and layerDefs when options change without recreating the service.

Parameter	Type	Description
sourceId	string	Source ID for the map
map	Map | null	Map instance
options	EsriServiceOptions	Service options including url, layers, layerDefs, etc.
sourceOptions	Record<string, unknown>	Optional raster source options

Returns: UseEsriServiceResult<DynamicMapService>

const { service, loading } = useDynamicMapService({
  sourceId: 'demographics',
  map,
  options: { url: 'https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer' },
});

useTiledMapService

Hook for TiledMapService.

Parameter	Type	Description
sourceId	string	Source ID for the map
map	Map | null	Map instance
options	EsriServiceOptions	Service options including url
sourceOptions	Record<string, unknown>	Optional raster source options

Returns: UseEsriServiceResult<TiledMapService>

const { service } = useTiledMapService({
  sourceId: 'basemap',
  map,
  options: { url: 'https://services.arcgisonline.com/arcgis/rest/services/World_Topo_Map/MapServer' },
});

useImageService

Hook for ImageService. A changed url or format rebuilds the service (and its source); renderingRule / mosaicRule changes are applied in place. Pass a memoized options object.

Parameter	Type	Description
sourceId	string	Source ID for the map
map	Map | null	Map instance
options	ImageServiceOptions	Service options including url, renderingRule, mosaicRule
sourceOptions	Record<string, unknown>	Optional raster source options

Returns: UseEsriServiceResult<ImageService>

const { service } = useImageService({
  sourceId: 'elevation',
  map,
  options: { url: 'https://sampleserver6.arcgisonline.com/arcgis/rest/services/NLCDLandCover/ImageServer' },
});

useFeatureService

Hook for FeatureService.

Parameter	Type	Description
sourceId	string	Source ID for the map
map	Map | null	Map instance
options	FeatureServiceOptions	Service options including url, where, outFields
sourceOptions	Record<string, unknown>	Optional GeoJSON source options

Returns: UseEsriServiceResult<FeatureService>

const { service } = useFeatureService({
  sourceId: 'parcels',
  map,
  options: {
    url: 'https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3',
    where: "STATE_NAME='California'",
  },
});

useVectorTileService

Hook for VectorTileService.

Parameter	Type	Description
sourceId	string	Source ID for the map
map	Map | null	Map instance
options	VectorTileServiceOptions	Service options including url
sourceOptions	Record<string, unknown>	Optional source options

Returns: UseEsriServiceResult<VectorTileService>

const { service } = useVectorTileService({
  sourceId: 'vtiles',
  map,
  options: { url: 'https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer' },
});

useVectorBasemapStyle

Hook for VectorBasemapStyle. Takes only { options } — no sourceId or map, because a basemap style is applied with map.setStyle(service.styleUrl) rather than added as a source. Returns service: null until a token or apiKey is supplied.

Parameter	Type	Default	Description
options.basemapEnum	string	'arcgis/streets'	Basemap style enum
options.token	string		Authentication token
options.apiKey	string		API key
options.language	string		Label language
options.worldview	string		Worldview

Returns: UseEsriServiceResult<VectorBasemapStyle>

const { service } = useVectorBasemapStyle({
  options: { basemapEnum: 'arcgis/navigation', token: 'YOUR_TOKEN' },
});

useEffect(() => {
  if (map && service) map.setStyle(service.styleUrl);
}, [map, service]);

usePortalItem

Deprecated

When you know the service type, pass the item id straight to the matching service hook as its url — e.g. useDynamicMapService({ options: { url: itemId } }). Use usePortalItem only when the type has to be auto-detected from the item.

Resolves an ArcGIS portal item id to the matching esri-gl service via serviceFromPortalItem and adds its source to the map. Re-resolves when itemId or map change, cleaning up the previous service.

Parameter	Type	Description
sourceId	string	Source ID for the map
map	Map | null	Map instance
itemId	string	ArcGIS portal item id to resolve
options	PortalItemServiceOptions	Auth (token/apiKey/authentication), portal, layerId, and per-kind source options

Returns:

Property	Type	Description
service	PortalResolvedService | null	The resolved service (source already on the map)
kind	PortalServiceKind | null	'dynamic', 'tiled', 'image', 'vector-tile', or 'feature'
url	string | null	The service URL the item resolved to
title	string | null	The portal item title
loading	boolean	Resolution in progress
error	Error | null	Resolution error, if any
reload	() => void	Re-resolve the item

const { service, kind, title, loading, error } = usePortalItem({
  sourceId: 'portal-src',
  map,
  itemId: 'a1b2c3d4e5f6',
  options: { token: 'YOUR_TOKEN' },
});

See the Portal Items guide for item-type mapping and Web Map resolution.

Task Hooks

These hooks wrap spatial tasks with loading/error state management.

useIdentifyFeatures

Hook for running IdentifyFeatures tasks.

Parameter	Type	Description
url	string	MapService URL
tolerance	number	Pixel tolerance for identify
returnGeometry	boolean	Include geometry in results

Returns:

Property	Type	Description
identify	(point, additionalOptions?) => Promise<GeoJSON.FeatureCollection>	Run identify at a point
loading	boolean	Whether a request is in progress
error	Error | null	Any error from the last request

The identify function accepts a { lng, lat } point and optional additional options including { map } to scope results to the current map extent.

const { identify, loading, error } = useIdentifyFeatures({
  url: 'https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer',
  tolerance: 3,
  returnGeometry: true,
});

const results = await identify({ lng: -118.24, lat: 34.05 }, { map });

useIdentifyImage

Hook for running IdentifyImage tasks on image services.

Parameter	Type	Description
url	string	ImageService URL
token	string	Optional authentication token
returnGeometry	boolean	Include geometry in results

Returns:

Property	Type	Description
identifyImage	(point, additionalOptions?) => Promise<IdentifyImageResponse>	Run identify at a point (the { results, location } response)
loading	boolean	Whether a request is in progress
error	Error | null	Any error from the last request

const { identifyImage, loading } = useIdentifyImage({
  url: 'https://sampleserver6.arcgisonline.com/arcgis/rest/services/NLCDLandCover/ImageServer',
});

const result = await identifyImage({ lng: -118.24, lat: 34.05 });

useQuery

Hook for running Query tasks with pagination support.

Parameter	Type	Description
url	string	Feature layer URL
where	string	SQL WHERE clause
outFields	string | string[]	Fields to return
returnGeometry	boolean	Include geometry in results

Returns:

Property	Type	Description
query	(additionalOptions?) => Promise<GeoJSON.FeatureCollection>	Run a single-page query
queryAll	(additionalOptions?) => Promise<GeoJSON.FeatureCollection>	Run a paginated query (supports maxPages)
loading	boolean	Whether a request is in progress
error	Error | null	Any error from the last request

const { query, queryAll, loading } = useQuery({
  url: 'https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3',
  where: "STATE_NAME='California'",
  outFields: ['STATE_NAME', 'POP2000'],
  returnGeometry: false,
});

const page = await query();
const all = await queryAll({ maxPages: 5 });

useFind

Hook for running Find tasks to search across multiple layers.

Parameter	Type	Description
url	string	MapService URL
searchText	string	Text to search for
layers	string | number[]	Layer IDs to search
searchFields	string | string[]	Fields to search in

Returns:

Property	Type	Description
find	(additionalOptions?) => Promise<GeoJSON.FeatureCollection>	Run the find operation
loading	boolean	Whether a request is in progress
error	Error | null	Any error from the last request

const { find, loading } = useFind({
  url: 'https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer',
  searchText: 'California',
  layers: [2, 3],
  searchFields: ['STATE_NAME'],
});

const results = await find();

useFeatureEditing

Hook for editing features on a FeatureService.

Parameter	Type	Description
service	FeatureService | null	The FeatureService instance to edit

Returns:

Property	Type	Description
addFeatures	(features, options?) => Promise<EditResult[]>	Add new features
updateFeatures	(features, options?) => Promise<EditResult[]>	Update existing features
deleteFeatures	(params) => Promise<EditResult[]>	Delete features by IDs or WHERE clause
applyEdits	(edits, options?) => Promise<ApplyEditsResult>	Batch add/update/delete in one call
loading	boolean	Whether an edit is in progress
error	Error | null	Any error from the last edit
lastResult	EditResult[] | ApplyEditsResult | null	Result of the last edit operation

const { service } = useFeatureService({ sourceId: 'parcels', map, options: { url: featureUrl } });
const { addFeatures, deleteFeatures, loading } = useFeatureEditing(service);

await addFeatures([{ type: 'Feature', geometry: { type: 'Point', coordinates: [-118, 34] }, properties: { name: 'New' } }]);
await deleteFeatures({ objectIds: [42] });

Context

EsriServiceProvider

Context provider for sharing a map instance with child Esri components.

import { EsriServiceProvider } from 'esri-gl/react';

function App() {
  const [map, setMap] = useState(null);
  return (
    <EsriServiceProvider map={map}>
      <MapView onLoad={setMap} />
      <LayerPanel />
    </EsriServiceProvider>
  );
}

useEsriMap

Hook to access the map instance from EsriServiceProvider.

Returns: Map | null

const map = useEsriMap();

EsriLayer

Generic layer component that adds a MapLibre GL layer to the map. Must be used within EsriServiceProvider.

Prop	Type	Description
sourceId	string	Source to use for the layer
layerId	string	Unique layer ID
type	string	Layer type: 'raster', 'fill', 'line', 'symbol', 'circle', etc.
paint	Record<string, unknown>	Paint properties
layout	Record<string, unknown>	Layout properties
beforeId	string	Insert layer before this layer ID

<EsriServiceProvider map={map}>
  <EsriLayer sourceId="parcels" layerId="parcels-fill" type="fill" paint={{ 'fill-color': '#0080ff', 'fill-opacity': 0.3 }} />
</EsriServiceProvider>