BasemapStyle

Class

The BasemapStyle class is used to load and apply ArcGIS basemap styles to a maplibre map.

The BasemapStyle class provides:

Loading of basemap styles from the ArcGIS Basemap Styles service.
Support for ArcGIS access tokens and sessions for authentication.
Support for style preferences such as language , places , and worldview .
An attribution control that meets Esri's attribution requirements.
Events for style load, attribution load, and error handling.

Use dark colors for code blocksCopy
import { Map } from 'maplibre-gl';
import { BasemapStyle } from '@esri/maplibre-arcgis';
// create a maplibre map
const map = new Map({
 container: 'map', // container id
 center: [-118.805,34.027], // starting position [lng, lat]
 zoom: 13 // starting zoom
});

// create a BasemapStyle
const basemapStyle = maplibreArcGIS.BasemapStyle.applyStyle(map, {
  style: 'arcgis/imagery',
  token: apiKey
});

Constructors

constructor

Class Constructor

BasemapStyle(options: IBasemapStyleOptions): BasemapStyle

Creates an instance of BasemapStyle. Creating basemap styles using the constructor directly is discouraged. The recommended method is to use the static BasemapStyle.applyStyle method.

Use dark colors for code blocksCopy
import { BasemapStyle } from '@esri/maplibre-arcgis';

const basemapStyle = new BasemapStyle({
 style: 'arcgis/streets',
 token  : 'YOUR_ACCESS_TOKEN',
 preferences: {
   language: 'en',
   worldview: 'unitedStatesOfAmerica',
   places: 'attributed'
 }
});

basemapStyle.applyTo(map);

basemapStyle.on('BasemapStyleLoad', (e) => {
 console.log('Basemap style loaded', e);
});

basemapStyle.on('BasemapAttributionLoad', (e) => {
 console.log('Attribution control loaded', e);
});

basemapStyle.on('BasemapStyleError', (e) => {
 console.error('Error loading basemap style', e);
});

Parameters

Parameter	Type	Notes
`options`	IBasemapStyleOptions	Configuration options for the basemap style.

Returns

BasemapStyle

Properties

Property	Type	Notes
`attributionControl`	`AttributionControl`	A reference to the map's AttributionControl.
`preferences`	`IBasemapPreferences`	Optional style preferences such as `language` and `places` .
`session`	`BasemapSession \| Promise<BasemapSession>`	A basemap session. Used for authentication.
`style`	`StyleSpecification`	The basemap style, formatted as MapLibre style specification JSON.
`styleId`	`string`	The ID of the saved style.
`token`	`string`	An ArcGIS access token. Used for authentication

attributionControl

Class Property

attributionControl: AttributionControl

A reference to the map's AttributionControl.

preferences

Class Property

preferences: IBasemapPreferences

Optional style preferences such as language and places .

session

Class Property

session: BasemapSession | Promise<BasemapSession>

A basemap session. Used for authentication.

style

Class Property

style: StyleSpecification

The basemap style, formatted as MapLibre style specification JSON.

styleId

Class Property

styleId: string

The ID of the saved style.

token

Class Property

token: string

An ArcGIS access token. Used for authentication

Methods

Method	Returns	Notes
`applyTo(map, maplibreStyleOptions?)`	`Map$1`	Applies the basemap style to a maplibre-gl map.
`loadStyle()`	`Promise<StyleSpecification>`	Loads the basemap style from the Basemap Styles service.
`off<K>(eventName, handler)`	`void`	Deregisters an event handler
`on<K>(eventName, handler)`	`void`	Registers an event handler
`setMap(map)`	`BasemapStyle`	Associates the BasemapStyle with a maplibre-gl map.
`updateStyle(options)`	`Promise<StyleSpecification>`	Updates the basemap style with new options and applies it to the current map.
`applyStyle(map, options)`	`BasemapStyle`	Creates, loads, and applies a new BasemapStyle to a maplibre map.
`getSelf(options)`	`Promise<BasemapSelfResponse>`	Static method that makes a `/self` request to the ArcGIS Basemap Styles service.
`url(options)`	`string`	Static method that returns a basemap style URL.

applyTo

Class Method

applyTo(map: Map$1, maplibreStyleOptions?: MaplibreStyleOptions): Map$1

Applies the basemap style to a maplibre-gl map.

Parameters

Parameter	Type	Notes
`map`	Map$1	A maplibre-gl map. The map may either be passed here or in the constructor.
`maplibreStyleOptions`	MaplibreStyleOptions	Optional style object for maplibre-gl, including the `transformStyle` function.

Returns

Map$1

The maplibre-gl map that the style was applied to.

loadStyle

Class Method

loadStyle(): Promise<StyleSpecification>

Loads the basemap style from the Basemap Styles service.

Returns

Promise<StyleSpecification>

The maplibre style specification of the basemap style, formatted properly.

off

Class Method

off<K>(eventName: K, handler: (data: BasemapStyleEventMap[K]) => void): void

Deregisters an event handler

Type Parameters

Parameter	Type
`K`	keyofBasemapStyleEventMap

Parameters

Parameter	Type	Notes
`eventName`	K	A basemap style event
`handler`	(data: BasemapStyleEventMap[K]) => void	Custom handler function

Returns

void

on

Class Method

on<K>(eventName: K, handler: (data: BasemapStyleEventMap[K]) => void): void

Registers an event handler

Type Parameters

Parameter	Type
`K`	keyofBasemapStyleEventMap

Parameters

Parameter	Type	Notes
`eventName`	K	A basemap style event
`handler`	(data: BasemapStyleEventMap[K]) => void	Custom handler function

Returns

void

setMap

Class Method

setMap(map: Map$1): BasemapStyle

Associates the BasemapStyle with a maplibre-gl map.

Parameters

Parameter	Type	Notes
`map`	Map$1	A maplibre-gl map.

Returns

BasemapStyle

The BasemapStyle object.

updateStyle

Class Method

updateStyle(options: IUpdateStyleOptions): Promise<StyleSpecification>

Updates the basemap style with new options and applies it to the current map.

Parameters

Parameter	Type	Notes
`options`	IUpdateStyleOptions	Options to customize the style enumeration and preferences such as language.

Returns

Promise<StyleSpecification>

applyStyle

static

Class Method

applyStyle(map: Map$1, options: IApplyStyleOptions): BasemapStyle

Creates, loads, and applies a new BasemapStyle to a maplibre map.

Parameters

Parameter	Type	Notes
`map`	Map$1	A maplibre-gl map to apply the basemap style to.
`options`	IApplyStyleOptions	Style options, including a style ID and authentication

Returns

BasemapStyle

BasemapStyle object

getSelf

static

Class Method

getSelf(options: { baseUrl?: string; token?: string }): Promise<BasemapSelfResponse>

Static method that makes a /self request to the ArcGIS Basemap Styles service.

Parameters

Parameter	Type	Notes
`options`	{ baseUrl?: string; token?: string* }*	Additional parameters including an ArcGIS access token

Returns

Promise<BasemapSelfResponse>

The response returned by the Basemap Styles service.

url

static

Class Method

url(options: IBasemapStyleOptions): string

Static method that returns a basemap style URL.

Parameters

Parameter	Type	Notes
`options`	IBasemapStyleOptions	Additional parameters including an ArcGIS access token

Returns

string

The URL of the specified ArcGIS basemap style with all included parameters