TiledMapService

Pre-rendered cached map tiles from ArcGIS Tiled Map Services. Fast performance, consistent styling, ideal for basemaps.

Live Demo

Interactive demo showing pre-rendered cached map tiles with layer visibility controls.

Quick Start

npm install esri-gl maplibre-gl

import { TiledMapService } from 'esri-gl';

const service = new TiledMapService('topo-source', map, {
  url: 'https://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer'
});

map.addLayer({
  id: 'topo-layer',
  type: 'raster',
  source: 'topo-source'
});

Constructor

new TiledMapService(id, map, esriServiceOptions, rasterSourceOptions?)

Parameter	Type	Description
id	string	Unique source ID for MapLibre
map	Map	MapLibre map instance
esriServiceOptions	object	Service configuration (see below)
rasterSourceOptions	object	Optional MapLibre raster source overrides

Options (esriServiceOptions)

Option	Type	Default	Description
url	string	required	ArcGIS MapServer URL (a cached/tiled service), or an ArcGIS portal item id
portal	string	—	Portal sharing REST URL used to resolve an item id url (defaults to ArcGIS Online)
fetchOptions	object	—	Deprecated — no longer forwarded to requests; use authentication instead.
token	string	—	ArcGIS authentication token
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	true	Fetch copyright text from service metadata

Authentication runs on ArcGIS REST JS. See the Authentication guide for tokens, API keys, and auth managers.

Methods

Method	Returns	Description
getMetadata()	Promise<ServiceMetadata>	Fetches (and caches) service metadata (tile info, extent, attribution)
setAttributionFromService()	Promise<void>	Sets map attribution from the service copyrightText
setToken(token)	void	Updates the authentication token and re-points the tile URLs
update()	void	No-op — tiled sources use static tile URLs and cannot be hot-updated
remove()	void	Removes the service source and its layers from the map

Properties

Property	Type	Description
sourceReady	Promise<void>	Resolves once the source has been added to the map (deferred when url is a portal item id)

Examples

Opacity Control

map.setPaintProperty('topo-layer', 'raster-opacity', 0.5);

Layer Visibility

map.setLayoutProperty('topo-layer', 'visibility', 'none');    // Hide
map.setLayoutProperty('topo-layer', 'visibility', 'visible'); // Show

Service Information

const info = await service.getMetadata();
console.log(info.tileInfo);      // Tile scheme information
console.log(info.fullExtent);    // Service extent
console.log(info.copyrightText); // Attribution text