TomTom Maps SDK for JavaScript

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.

Property Default Sets
mapLibre — MapLibre's map options (container, center, zoom, bounds, pitch, interactive…), typed MapLibreOptions
style 'streetLight' The map style, as a standard style id or a standard style with the parts it includes
events — How user events are detected and timed, and the cursors they show (map-level event configuration)
attribution — Your own credits in the map's attribution
registerMapLibreWorker true Whether the SDK starts MapLibre's web worker from the copy your bundler builds (Vite projects)
transformRequest — A function that holds or rewrites each request the map makes, after the SDK has built it (Holding and rewriting map requests)
apiKey, language, geopoliticalView, … The global configuration Any global configuration property, for this map only

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' },
});

Related examples

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:

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>'] },
});

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.

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.

When How it arrives code
The browser cannot create a WebGL2 context The constructor throws WEBGL_UNSUPPORTED
commonBaseURL is neither https: nor http: on a loopback address The constructor throws INSECURE_BASE_URL
The style fails to load The error handlers get it, a setStyle switch rejects with it, and so does module creation By HTTP status (INVALID_CREDENTIALS, INSUFFICIENT_PERMISSIONS, RATE_LIMITED, …), NETWORK_NOT_AVAILABLE with no response, otherwise STYLE_LOAD_FAILED
A tile, sprite or glyph fails to load The error handlers get it, with the source in sourceId. A tile answered with 404 isn't reported By HTTP status, NETWORK_NOT_AVAILABLE with no response, otherwise INTERNAL
The browser takes the WebGL context away The error handlers get it WEBGL_CONTEXT_LOST 
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');
});

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

Next steps