TomTom map object

Overview

TomTomMap wraps a MapLibre GL JS map. It loads a TomTom style with your API key, coordinates the user events of every module and keeps the SDK's state through style switches. The MapLibre map stays fully exposed.

Initialization

Basic setup

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { TomTomMap } from '@tomtom-org/maps-sdk/map';

TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY' });

const map = new TomTomMap({
    mapLibre: {
        container: 'map-container',
        center: [4.9041, 52.3676],
        zoom: 12
    },
    style: 'streetDark',
    language: 'en-US'
});

Constructor parameters

TomTomMap takes one TomTomMapParams object. Only mapLibre.container is required.

• Properties you pass here override the global configuration you set with TomTomConfig.instance.put().
• The SDK sets MapLibre's style, attributionControl and transformRequest itself, so MapLibreOptions leaves them out. To route TomTom requests through your own proxy, set commonBaseURL.

Map styles

style picks the style the map opens with, and map.setStyle(style) switches it at runtime. By default, the switch keeps every module's data and configuration. setStyle returns a promise that resolves once every module has restored itself. getStyleInput() returns the style you last gave it. The Map styles guide covers the standard styles, style parts, keeping or dropping state and listening to style changes.

Event configuration

events configures how user events behave for every module, including precision mode, hit-box padding, hover timing and cursors. map.updateEventsConfig(config) changes it at runtime:

const map = new TomTomMap({
    mapLibre: { container: 'map' },
    events: { precisionMode: 'point-then-box', paddingBoxPx: 10, cursorOnHover: 'pointer' },
});

map.updateEventsConfig({ longHoverDelayOnStillMapMS: 600 });

Map-level event configuration lists every option and its default. A module's own events overrides the cursor and hover settings for its features.

Accessing MapLibre

map.mapLibreMap is the MapLibre Map itself, so any MapLibre API, control or plugin works on a TomTom map:

import { NavigationControl } from 'maplibre-gl';

const map = new TomTomMap({ mapLibre: { container: 'map' } });

map.mapLibreMap.addControl(new NavigationControl(), 'top-right');
map.mapLibreMap.on('moveend', () => {
    console.log('Camera:', map.mapLibreMap.getCenter());
});

Use it for controls, markers, popups, camera moves, tile overlays and third-party plugins. For your own GeoJSON data, use the Custom GeoJSON module, which keeps it on the map across style switches. About MapLibre lists which SDK feature replaces which raw MapLibre call.

Map readiness

map.mapReady is true once the style has loaded, and false again during every style switch.

• Module factories (get(), create()) wait for the map themselves, so call them right after constructing it.
• For your own code, await setStyle, or register a style change handler.

Map errors

The map reports its failures as a TomTomMapError. Its code is one of the codes service errors use. Its canRetry is true when the failure clears on its own (a rate limit, a 5xx or no connection). Its sdkVersion helps with bug reports.

import { TomTomMap, TomTomMapError } from '@tomtom-org/maps-sdk/map';

let map;
try {
    map = new TomTomMap({ mapLibre: { container: 'map' } });
} catch (error) {
    if (error instanceof TomTomMapError && error.code === 'WEBGL_UNSUPPORTED') showStaticImage();
    else throw error;
}

const removeErrorHandler = map.addErrorHandler((error) => {
    if (error.code === 'INVALID_CREDENTIALS') showMessage('The map could not load: check the API key');
    else if (error.code === 'INSUFFICIENT_PERMISSIONS') showMessage('The map could not load: check the domains the key allows');
});

• INVALID_CREDENTIALS is a key the API does not know (401). INSUFFICIENT_PERMISSIONS is a valid key that the API refuses for this page (403), most often because of its domain restriction. See A key refused access.
• While no handler is registered, the map logs each failure with console.error, as MapLibre does.
• A failed tile does not stop the map. MapLibre keeps drawing the others, so log the failure instead of tearing the map down.

Language configuration

language sets the language of the map labels, and map.setLanguage('fr-FR') changes it at runtime. If you don't set it, each label is in its local language. Both survive every style switch. See Map language. The traffic incident descriptions follow it too.

const map = new TomTomMap({
    mapLibre: { container: 'map' },
    language: 'fr-FR'
});

Geopolitical view

geopoliticalView sets whose perspective the map draws disputed borders and names from, and map.setGeopoliticalView(view) switches it at runtime. If you set it in the global configuration, it applies to services too. See Geopolitical views.

const map = new TomTomMap({
    mapLibre: { container: 'map' },
    geopoliticalView: 'IN'
});

map.setGeopoliticalView('PK');

API reference

TomTomMap API reference

Key methods summary

• mapLibreMap - The underlying MapLibre map.
• mapReady - Whether the style has loaded.
• setStyle(style, options?) - Switches the style. Resolves once the modules are restored.
• getStyleInput() - The style last given.
• addStyleChangeHandler(handler) - Runs code around a style switch. Returns a function that unsubscribes it.
• addErrorHandler(handler) - Receives every map failure as a TomTomMapError. Returns a function that unsubscribes it.
• setLanguage(language), setGeopoliticalView(geopoliticalView) - Relabel and redraw the map already on screen.
• updateEventsConfig(config) - Changes the map-level event configuration.
• getBBox() - The visible area as [west, south, east, north].
• styleLightDarkTheme - Whether the loaded style is 'light' or 'dark', for binding your own UI.
• mapColors - The map's semantic colours and accent, as the Styling Foundations module last published them.

Next steps

• Modules: add functionality with modules
• Map styles: the standard styles, and switching them
• User interaction events: handle interactions
• Services quickstart: connect TomTom services