MLMap

Defined in: packages/core/src/components/ml-map.ts:154

MLMap custom element for rendering MapLibre maps from YAML/JSON configuration.

Events

Dispatched on the element as CustomEvents; listen with addEventListener.

Event	When
ml-map:load	Map loaded and ready for interaction
ml-map:error	Error during initialization or runtime
ml-map:loading	Loading configuration from URL
ml-map:layer-added	Layer was added to the map
ml-map:layer-removed	Layer was removed from the map
ml-map:layer-data-loading	Layer data is being fetched
ml-map:layer-data-loaded	Layer data loaded successfully
ml-map:layer-data-error	Layer data failed to load
ml-map:layer-click	User clicked on a layer feature
ml-map:layer-hover	User hovered over a layer feature
ml-map:markers-added	Standalone markers: pins were added
ml-map:marker-click	User clicked a standalone marker
ml-map:marker-icon-error	A marker icon failed (unsafe scheme or load error); the default pin was substituted
ml-map:image-error	A declared images: entry failed (unsafe scheme, load or register error)
ml-map:parameter-change	A params-panel control wrote a state key
ml-map:layer-visibility	A params-panel checkbox toggled a layer
ml-map:camera-fit	The fitTo camera framed its source’s data (detail: source, bounds)

Extends

• HTMLElement

Constructors

Constructor

new MLMap(): MLMap

Defined in: node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.dom.d.ts:13847

Returns

MLMap

Inherited from

HTMLElement.constructor

Accessors

config

Get Signature

get config(): {[key: string]: any; } | null

Defined in: packages/core/src/components/ml-map.ts:224

Get the current map configuration

Returns

{[key: string]: any; } | null

Set Signature

set config(value): void

Defined in: packages/core/src/components/ml-map.ts:239

Set the map configuration programmatically.

Remarks

Accepts a MapBlock object or its JSON string; both are validated like every other config path, whether assigned before or after the element connects. Assigning a value that is JSON-equal to the config currently applied is a no-op, so a framework re-binding an equal object does not rebuild the map. Assigning null clears the stored config without touching a rendered map.

Parameters

Parameter	Type
value	string | {[key: string]: any; } | null

Returns

void

---

observedAttributes

Get Signature

get static observedAttributes(): string[]

Defined in: packages/core/src/components/ml-map.ts:217

Observed attributes that trigger attributeChangedCallback

Returns

string[]

Methods

addEventListener()

Call Signature

addEventListener<K>(type, listener, options?): void

Defined in: packages/core/src/components/ml-map.ts:1360

Type Parameters

Type Parameter
K extends keyof MLMapEventMap

Parameters

Parameter	Type
type	K
listener	(this, event) => unknown
options?	boolean | AddEventListenerOptions

Returns

void

Inherited from

HTMLElement.addEventListener

Call Signature

addEventListener<K>(type, listener, options?): void

Defined in: packages/core/src/components/ml-map.ts:1365

Type Parameters

Type Parameter
K extends keyof HTMLElementEventMap

Parameters

Parameter	Type
type	K
listener	(this, event) => unknown
options?	boolean | AddEventListenerOptions

Returns

void

Inherited from

HTMLElement.addEventListener

Call Signature

addEventListener(type, listener, options?): void

Defined in: packages/core/src/components/ml-map.ts:1370

Parameters

Parameter	Type
type	string
listener	EventListenerOrEventListenerObject
options?	boolean | AddEventListenerOptions

Returns

void

Inherited from

HTMLElement.addEventListener

---

addLayer()

addLayer(layer): Promise<void>

Defined in: packages/core/src/components/ml-map.ts:1302

Add a layer to the map

Parameters

Parameter	Type	Description
layer	any	Layer configuration object

Returns

Promise<void>

Promise that resolves when the layer is added

Example

await mapEl.addLayer({
  id: 'new-layer',
  type: 'circle',
  source: {
    type: 'geojson',
    data: { type: 'FeatureCollection', features: [] }
  },
  paint: { 'circle-radius': 6, 'circle-color': '#ff0000' }
});

---

attributeChangedCallback()

attributeChangedCallback(name, oldValue, newValue): void

Defined in: packages/core/src/components/ml-map.ts:348

Called when an observed attribute changes

Parameters

Parameter	Type
name	string
oldValue	string | null
newValue	string | null

Returns

void

---

connectedCallback()

connectedCallback(): void

Defined in: packages/core/src/components/ml-map.ts:306

Called when the element is added to the DOM

Returns

void

---

disconnectedCallback()

disconnectedCallback(): void

Defined in: packages/core/src/components/ml-map.ts:341

Called when the element is removed from the DOM

Returns

void

---

getMap()

getMap(): maplibregl.Map | null

Defined in: packages/core/src/components/ml-map.ts:1191

Get the underlying MapLibre GL map instance

Returns

maplibregl.Map | null

The MapLibre GL map instance, or null if not initialized

See

MLMap.mapReady — the promise form; resolves once loaded and removes the need for the load-listener + null-guard shown below.

Example

const mapEl = document.querySelector('ml-map');

mapEl.addEventListener('ml-map:load', () => {
  const map = mapEl.getMap();
  map.flyTo({ center: [-122.4, 37.8], zoom: 14 });
});

---

getRenderer()

getRenderer(): MapRenderer | null

Defined in: packages/core/src/components/ml-map.ts:1270

Get the MapRenderer instance

Returns

MapRenderer | null

The MapRenderer instance, or null if not initialized

---

isLoaded()

isLoaded(): boolean

Defined in: packages/core/src/components/ml-map.ts:1279

Check if the map is loaded

Returns

boolean

True if the map has finished loading

---

mapReady()

mapReady(): Promise<maplibregl.Map>

Defined in: packages/core/src/components/ml-map.ts:1211

Resolve with the underlying MapLibre map once the document has loaded.

Returns

Promise<maplibregl.Map>

Remarks

The readiness idiom (R3): replaces the ml-map:load listener + getMap() null-guard boilerplate every page-code snippet needed. Resolves immediately when the map is already loaded; otherwise resolves on the next ml-map:load and rejects on ml-map:error (config parse failure, renderer construction failure, or a runtime map error).

Example

const map = await document.querySelector('ml-map').mapReady();
map.flyTo({ center: [-122.4, 37.8], zoom: 14 });

---

reload()

reload(): Promise<void>

Defined in: packages/core/src/components/ml-map.ts:1340

Reload configuration from the current source

Returns

Promise<void>

Promise that resolves when reload is complete

---

removeEventListener()

Call Signature

removeEventListener<K>(type, listener, options?): void

Defined in: packages/core/src/components/ml-map.ts:1375

Type Parameters

Type Parameter
K extends keyof MLMapEventMap

Parameters

Parameter	Type
type	K
listener	(this, event) => unknown
options?	boolean | EventListenerOptions

Returns

void

Inherited from

HTMLElement.removeEventListener

Call Signature

removeEventListener<K>(type, listener, options?): void

Defined in: packages/core/src/components/ml-map.ts:1380

Type Parameters

Type Parameter
K extends keyof HTMLElementEventMap

Parameters

Parameter	Type
type	K
listener	(this, event) => unknown
options?	boolean | EventListenerOptions

Returns

void

Inherited from

HTMLElement.removeEventListener

Call Signature

removeEventListener(type, listener, options?): void

Defined in: packages/core/src/components/ml-map.ts:1385

Parameters

Parameter	Type
type	string
listener	EventListenerOrEventListenerObject
options?	boolean | EventListenerOptions

Returns

void

Inherited from

HTMLElement.removeEventListener

---

removeLayer()

removeLayer(layerId): void

Defined in: packages/core/src/components/ml-map.ts:1311

Remove a layer from the map

Parameters

Parameter	Type	Description
layerId	string	ID of the layer to remove

Returns

void

---

setLayerVisibility()

setLayerVisibility(layerId, visible): void

Defined in: packages/core/src/components/ml-map.ts:1321

Set layer visibility

Parameters

Parameter	Type	Description
layerId	string	ID of the layer
visible	boolean	Whether the layer should be visible

Returns

void

---

updateLayerData()

updateLayerData(layerId, data): void

Defined in: packages/core/src/components/ml-map.ts:1331

Update layer data

Parameters

Parameter	Type	Description
layerId	string	ID of the layer
data	GeoJSON	New GeoJSON data

Returns

void