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 add your own credits, set attribution. To route TomTom requests through your own proxy, set commonBaseURL.

Holding and rewriting map requests

To hold or rewrite map requests, pass transformRequest to TomTomMap. It runs after the SDK's own and may return a promise.

It gets the request the SDK built, with its URL, headers and credentials, and returns the one to send. Return a promise to hold the request until it resolves, for example while your proxy mints a session:

const map = new TomTomMap({
    transformRequest: async (request, resourceType) => {
        await ensureSession();
        return request;
    },
    mapLibre: { container: 'map' },
});

• It runs for every request, every tile included, so keep it fast. Await a promise you already hold rather than starting a new call each time.
• The Landmarks3D plugin fetches its models with fetch, so they don't pass through it.
• With an apiKey, the URL carries it as key=. Keep that URL out of your logs.
• It stays in place when setLanguage or setGeopoliticalView changes the requests the SDK builds.
• When it throws or its promise rejects, that request fails.

Related examples

• Hold map requests - The map's tile requests held behind a toggle, counted, then released

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.

Copyright attribution

In its bottom-right corner, the map shows the copyright notices of the data it draws. They include TomTom's and those of the third parties the style credits, such as OpenStreetMap. The SDK always adds MapLibre's attribution control, expanded, so MapLibreOptions has no attributionControl to turn it off.

Under the SDK license (clause 5.2), you agree not to remove, obscure, mask or change these notices. Keep the attribution visible and readable:

• Don't hide it with CSS, such as display: none on .maplibregl-ctrl-attrib, and don't remove the control through mapLibreMap.
• Don't cover it with your own panels, badges, overlays or controls. Place a corner element clear of the attribution.
• For a panel across the map's bottom edge, such as a bottom sheet, leave a gap below it for the attribution, about 32 px, or end the map's container above the panel.
• Don't change its text.
• A source you add with an attribution of its own shows in the same control. Keep what its provider asks for there too.

Your own credits

Add your own credits with attribution.credits. They show next to TomTom's and stay across style switches.

const map = new TomTomMap({
    mapLibre: { container: 'map' },
    attribution: { credits: ['Weather data by <a href="https://open-meteo.com/">Open-Meteo.com</a>'] },
});

• Each credit is text or HTML, such as a link.
• A credit that another credit already contains shows once. So a credit that repeats the style's own wording, such as © OpenStreetMap, doesn't show twice.

The GeoJSON heatmap example credits the dataset it shows, and keeps the credit as you switch styles.

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. If the style fails to load, they reject. See Map errors.
• 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 APIs and 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 (403). Either the key's domain restriction refused the page, or the key has no access to the Maps API. Unlike a service error, a TomTomMapError has no apiErrorCode to tell the two apart, so check both. See A key refused access.
• After the style fails to load, module creation rejects with its TomTomMapError, and so does every module call that waits for the map, such as showRoutes() or show(), until a setStyle loads a style. An await on create() or get() lands in your catch. Once a style loads, create again only the modules whose create() or get() rejected. The others restore themselves.
• 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