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.
Registers a handler to be notified when the map style changes.
A StyleChangeHandler object with callbacks for style change events.
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');
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:
keepState: true)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.
OptionalkeepState?: booleanWhether to preserve SDK-rendered items and configurations when changing styles.
When true (default), maintains traffic layers, routes, markers, and other SDK features.
When false, performs a clean style switch without preserving previous state.
Behavior:
false during the transitiontrue when the new style is fully loadedState Preservation (keepState: true):
Clean Switch (keepState: false):
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', { keepState: false });
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: