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

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

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

6
const map = new TomTomMap({
7
    mapLibre: {
8
        container: 'map-container',
9
        center: [4.9041, 52.3676],
10
        zoom: 12
11
    },
12
    style: 'streetDark',
13
    language: 'en-US'
14
});

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 place the attribution or 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:

1
const map = new TomTomMap({
2
    transformRequest: async (request, resourceType) => {
3
        await ensureSession();
4
        return request;
5
    },
6
    mapLibre: { container: 'map' },
7
});

• 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:

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

6
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:

1
import { NavigationControl } from 'maplibre-gl';
2

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

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

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

By default 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. TomTom and OpenStreetMap show as logos, and each logo keeps the link of the credit it replaces. Any other credit a style source declares, such as your own data’s, follows as text, so nothing is dropped.

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 .tomtom-attribution-logos, 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, or move the attribution.
• For a panel across the map’s bottom edge, such as a bottom sheet, lift the attribution above the panel with padding: { vertical: panelHeight + 8 }, 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.

Placing the attribution

Move the attribution to another corner with attribution.position, and set its distance to the map’s edges with attribution.padding. By default, it sits 12px from the side edge and 8px from the top or bottom one: { horizontal: 12, vertical: 8 }. AttributionOptions lists the options.

These options only change where the attribution sits. None of them removes it or swaps the logos for plain text: the map always shows them, and the license terms above apply wherever you place them.

1
const map = new TomTomMap({
2
    mapLibre: { container: 'map' },
3
    // Another corner, 16px from both edges; padding also takes { horizontal, vertical }
4
    attribution: { position: 'top-left', padding: 16 },
5
});

• The logos are black with a white outline, on light and dark styles alike.
• Pick a corner and a padding where the attribution stays readable and nothing of yours covers it.

Your own credits

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

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

• Each credit is text or HTML. Its text and its links to http or https addresses show; scripts, images and other markup don’t.
• A credit that repeats one the map already shows, such as © OpenStreetMap, shows once.
• Your credits add to the map’s and never replace them.
• credits sits beside position and padding in the same object.

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

The backdrop

A soft, blurred backdrop sits behind the logos so they stand out from the map’s labels. It fades out past the logos without moving them, and follows the style’s theme: light over a light style, dark over a dark one.

Where your own UI already gives the attribution a calm background, turn the backdrop off with attribution.backdrop:

1
const map = new TomTomMap({
2
    mapLibre: { container: 'map' },
3
    attribution: { backdrop: false },
4
});

This only removes the backdrop. The logos stay, and so do the license terms.

Related examples

• Attribution playground - The copyright logos placed in any corner, clear of a bottom sheet, with or without their backdrop, on every standard style

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 error codes every SDK error shares, service errors included. Its canRetry is true when the failure clears on its own, such as a rate limit, a 5xx or no connection.

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

3
let map;
4
try {
5
    map = new TomTomMap({ mapLibre: { container: 'map' } });
6
} catch (error) {
7
    if (error instanceof TomTomMapError && error.code === 'WEBGL_UNSUPPORTED') showStaticImage();
8
    else throw error;
9
}
10

11
// explainRefusedKey is in the Errors guide, under A key refused access.
12
const removeErrorHandler = map.addErrorHandler((error) => {
13
    const explanation = explainRefusedKey(error);
14
    if (explanation) showMessage(`The map could not load: ${explanation}`);
15
    else if (error.code === 'WEBGL_CONTEXT_LOST') showMessage('The map stopped drawing: reload the page');
16
    else console.warn(error);
17
});

• A refused key reads as it does on a service call. INVALID_CREDENTIALS is a key the API does not know (401). INSUFFICIENT_PERMISSIONS is a valid key that the API refuses (403). Its apiErrorCode says why, and on a Private Preview API, privatePreviewAccess names the access to request. A key refused access reads them the same way for the map and a service call.
• 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.

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

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.

1
const map = new TomTomMap({
2
    mapLibre: { container: 'map' },
3
    geopoliticalView: 'IN'
4
});
5

6
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