Constructs a new TomTom Map instance and attaches it to a DOM element.
Combined TomTom and MapLibre parameters for map initialization. Includes API key, style, events, and MapLibre options like container, center, zoom, etc. See TomTomMapParams for all available parameters.
Initialization Process:
mapParams with global configurationmapReady to true when completeConfiguration Priority:
Minimal initialization:
const map = new TomTomMap({
key: 'YOUR_API_KEY',
mapLibre: {
container: 'map',
center: [0, 0],
zoom: 2
}
});
Full configuration:
const map = new TomTomMap({
key: 'YOUR_API_KEY',
style: {
type: 'standard',
id: 'standardLight',
include: ['trafficFlow', 'hillshade']
},
language: 'en-US',
events: {
precisionMode: 'point-then-box',
paddingBoxPx: 10
},
mapLibre: {
container: 'map',
center: [-122.4194, 37.7749],
zoom: 13,
pitch: 45,
bearing: -17.6,
antialias: true,
maxZoom: 18,
minZoom: 8
}
});
ReadonlymapThe underlying MapLibre GL JS Map instance.
When to Use:
Important:
Add custom layer:
map.mapLibreMap.addLayer({
id: 'custom-layer',
type: 'circle',
source: 'my-data',
paint: {
'circle-radius': 6,
'circle-color': '#ff0000'
}
});
Indicates whether the map style has been fully loaded and is ready for interaction.
Whether the loaded style draws a light or a dark map.
The SDK's own overlays read it to pick text and halo colours that stay legible over the base map, and it is the property to bind your own UI to rather than parsing the style ID.
A standard style is classified from its ID. A custom style reads 'light' until it has
loaded — nothing about it is known before that — and is then classified from the colour its
background layer paints the canvas with; a custom style with no readable background colour
stays 'light'. So read it inside an
onStyleChanged handler, or after awaiting
setStyle, rather than right after calling it.
Registers a handler to be notified when the map style changes.
A StyleChangeHandler object with callbacks for style change events.
An unsubscribe function that removes this handler. Call it when the
handler's owner (e.g. a custom overlay) is torn down — otherwise the handler,
and everything it closes over, lives for the lifetime of the map. Mirrors the
disposer returned by module event handlers (module.events.on(...)).
When to Use:
Handler Lifecycle:
onStyleAboutToChange() - Called before the style change beginsonStyleChanged() - Called after the new style has been fully loadedMultiple Handlers:
Important Notes:
Basic usage:
map.addStyleChangeHandler({
onStyleAboutToChange: () => {
console.log('Style is changing...');
},
onStyleChanged: () => {
console.log('Style changed successfully!');
}
});
// Later trigger the handlers
map.setStyle('standardDark');
Unsubscribe when the owner is torn down:
const unsubscribe = map.addStyleChangeHandler({
onStyleChanged: () => reattachCustomLayers(),
});
// Later, when the overlay is removed:
unsubscribe();
Preserve custom layers across style changes:
let customLayerData = null;
map.addStyleChangeHandler({
onStyleAboutToChange: () => {
// Save custom layer data before style changes
if (map.mapLibreMap.getLayer('my-custom-layer')) {
customLayerData = map.mapLibreMap.getSource('my-data')._data;
map.mapLibreMap.removeLayer('my-custom-layer');
map.mapLibreMap.removeSource('my-data');
}
},
onStyleChanged: () => {
// Restore custom layer after new style is loaded
if (customLayerData) {
map.mapLibreMap.addSource('my-data', {
type: 'geojson',
data: customLayerData
});
map.mapLibreMap.addLayer({
id: 'my-custom-layer',
type: 'circle',
source: 'my-data',
paint: { 'circle-radius': 6, 'circle-color': '#007cbf' }
});
}
}
});
Async handler for external API calls:
map.addStyleChangeHandler({
onStyleAboutToChange: async () => {
await saveStateToAPI(map.getStyle());
},
onStyleChanged: async () => {
await loadStateFromAPI();
}
});
Update UI based on style:
map.addStyleChangeHandler({
onStyleAboutToChange: () => {
document.body.classList.add('style-changing');
},
onStyleChanged: () => {
document.body.classList.remove('style-changing');
const style = map.getStyle();
if (typeof style === 'string' && style.includes('Dark')) {
document.body.classList.add('dark-mode');
} else {
document.body.classList.remove('dark-mode');
}
}
});
Retrieves the current visible map area as a GeoJSON bounding box.
A GeoJSON BBox array
in the format [west, south, east, north] representing the map's current viewport bounds.
Return Format:
[minLongitude, minLatitude, maxLongitude, maxLatitude]Get current bounds:
const bbox = map.getBBox();
console.log('Bounds:', bbox);
// Output: [-122.5, 37.7, -122.3, 37.8]
// [west, south, east, north]
Use bounds for spatial query:
const bbox = map.getBBox();
const results = await searchAPI.searchInBoundingBox({
bbox: bbox,
query: 'restaurants'
});
Retrieves the current style configuration of the map.
The current StyleInput configuration, or undefined if no style is set.
Returns the style configuration as it was set, not the fully resolved MapLibre style object. Use this to inspect or store the current style configuration for later restoration.
Return Value:
'standardLight') for simple style configurationstype, id, and optional include properties for detailed configurationsundefined if no style has been explicitly setconst currentStyle = map.getStyle();
console.log('Current style:', currentStyle);
// Save style for later
const savedStyle = map.getStyle();
// Later, restore it
if (savedStyle) {
map.setStyle(savedStyle);
}
Conditional logic based on current style:
const style = map.getStyle();
if (typeof style === 'string' && style.includes('Dark')) {
console.log('Dark mode is active');
}
Changes the language of the map.
The language to be used in map translations.
Behavior:
Language Format:
'en', 'fr', 'de', 'ja', 'zh''en-US', 'en-GB', 'zh-CN', 'pt-BR'-), only the language portion is used for labelsPersistence:
Use locale-specific codes:
// Use Simplified Chinese
map.setLanguage('zh-CN');
// Use Brazilian Portuguese
map.setLanguage('pt-BR');
Language switcher UI:
const languageSelector = document.getElementById('lang-select');
languageSelector.addEventListener('change', (e) => {
map.setLanguage(e.target.value);
});
Changes the map style dynamically without reloading the entire map.
The new style to apply. Can be a string ID or a detailed style configuration.
Configuration options for the style change behavior, see SetStyleOptions.
A promise that resolves once the new style is loaded and every registered StyleChangeHandler has finished — including the SDK modules restoring themselves. Awaiting it is optional; it is the moment after which the map is safe to read and draw on again.
If the style itself fails to load, leaving mapReady false and the map on
the style it had. A tile or source that fails to load does not fail the switch.
Carried-over state (the default):
Clean switch (resetState: true):
Both keep the map language: it is configuration, not state, and it survives every style change until setLanguage changes it.
Behavior:
false for the duration of the transitiononStyleAboutToChange handler, then hands the new style to MapLibretrue and awaits every
onStyleChanged handler in registration ordersetStyle call made while another one is still in flight supersedes it: the older
call's style is never applied and its promise resolves as soon as that is knownresetState: true doubles as a reset of the SDK modules over the current styleWait for the switch to complete before drawing on the map:
await map.setStyle('standardDark');
// modules have restored themselves; map.mapReady is true again
Style change with detailed configuration:
map.setStyle({
type: 'standard',
id: 'standardLight',
include: ['trafficFlow', 'hillshade']
});
Clean style switch without state preservation:
// Complete reset - removes all SDK layers and modules
map.setStyle('standardDark', { resetState: true });
With style change handlers:
map.addStyleChangeHandler({
onStyleAboutToChange: () => {
console.log('Preparing for style change...');
},
onStyleChanged: () => {
console.log('New style applied!');
}
});
map.setStyle('standardDark');
Main TomTom Map class for displaying interactive maps in web applications.
This is the entry point for rendering TomTom maps. It wraps MapLibre GL JS and provides a simplified, enhanced API for common mapping tasks.
Remarks
Key Features:
Architecture:
Example
Basic map initialization:
Example
With modules and configuration: