TomTom Map object

Overview

TomTomMap is a lightweight wrapper around MapLibre GL JS that simplifies initialization and integration with TomTom services. It provides a high-level interface while preserving full access to MapLibre’s capabilities.

Initialization

Basic Setup

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

3
const map = new TomTomMap({
4
    mapLibre: {
5
        container: 'map-container',
6
        center: [4.9041, 52.3676],
7
        zoom: 12
8
    }
9
});

With Configuration

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

3
// Set global configuration
4
TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY' });
5

6
// Create map with TomTom-specific parameters
7
const map = new TomTomMap({
8
    mapLibre: {
9
        container: 'map-container',
10
        center: [-122.4194, 37.7749],
11
        zoom: 13,
12
        pitch: 45,
13
        bearing: -17.6
14
    },
15
    // TomTom parameters (optional if globally configured)
16
    apiKey: 'YOUR_API_KEY', // Override global config
17
    language: 'en-US',
18
    style: 'standardDark'
19
});

Constructor Parameters

TomTomMap accepts a single configuration object of type TomTomMapParams , which includes:

1. MapLibre options: Standard MapLibre configuration (container, center, zoom, etc.) - see MapLibreOptions
2. TomTom options: SDK-specific configuration (style, events, etc.)
3. Global config properties: Optional overrides for apiKey, language, and other global settings

All properties except mapLibre.container are optional. Global configuration properties (apiKey, language, etc.) can be set globally via TomTomConfig.instance.put() and will be automatically merged. Parameters passed to the constructor override global configuration, allowing per-map customization.

Map Styles

Using Standard Styles

TomTom provides several standard styles. A standard style is predefined and hosted by TomTom, making it easy to use.

You can quickly specify a standard style by its string identifier:

1
// Simple style reference
2
const map = new TomTomMap({
3
    mapLibre: {
4
        container: 'map'
5
    },
6
    style: 'standardDark'
7
});

Available standard styles: standardLight (default), standardDark, drivingLight, drivingDark, monoLight, monoDark, satellite

Advanced Style Configuration

1
const map = new TomTomMap({
2
    mapLibre: {
3
        container: 'map'
4
    },
5
    style: {
6
        type: 'standard',
7
        id: 'standardLight',
8
        include: ['trafficFlow', 'trafficIncidents', 'hillshade']
9
    }
10
});

Learn more about Map Styles →

Dynamic Style Changes

Change the map style at runtime using the setStyle method:

1
// Change style at runtime
2
map.setStyle('standardDark');
3

4
// With options
5
map.setStyle('standardDark', { keepState: true });

When keepState: true (default), the map preserves SDK module layers, traffic, routes, and other features during the style change.

Event Configuration

Configure how the map responds to user interactions:

1
const map = new TomTomMap({
2
    mapLibre: {
3
        container: 'map'
4
    },
5
    events: {
6
        precisionMode: 'box',
7
        paddingBoxPx: 10,
8
        cursorOnHover: 'pointer'
9
    }
10
});

Precision Modes

• point: Exact click location
• box: Click area with configurable padding
• point-then-box: Tries exact location first, then expands to box if nothing found

Learn more about User Interaction Events →

Accessing MapLibre

Direct access to the underlying MapLibre instance:

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

3
// Access MapLibre map
4
const mapLibreMap = map.mapLibreMap;
5

6
// Use MapLibre API directly
7
mapLibreMap.on('moveend', () => {
8
    console.log('Camera:', mapLibreMap.getCenter());
9
});
10

11
// Add custom layers
12
mapLibreMap.addLayer({
13
    id: 'custom-layer',
14
    type: 'circle',
15
    source: 'my-data'
16
});

Use Cases:

• Add custom layers and sources
• Listen to MapLibre-specific events
• Access advanced camera controls
• Integrate third-party MapLibre plugins

Map Readiness

The mapReady property indicates when the map is fully loaded:

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

3
if (map.mapReady) {
4
    // Safe to initialize modules
5
    const trafficFlowModule = await TrafficFlowModule.get(map);
6
}
7

8
// Or wait for style to load
9
map.mapLibreMap.on('load', () => {
10
    console.log('Map is ready');
11
});

Important: mapReady becomes false during style changes and returns to true when the new style loads.

Style Change Handlers

Register callbacks to handle style transitions:

1
map.addStyleChangeHandler({
2
    onStyleAboutToChange: () => {
3
        console.log('Style changing...');
4
        // Prepare for style change
5
    },
6
    onStyleChanged: () => {
7
        console.log('New style loaded');
8
        // Reinitialize or update modules
9
    }
10
});

This is useful for modules or custom code that needs to react to style changes triggered by the setStyle method.

Language Configuration

Set the display language for map labels:

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

Supported languages include standard locale codes (e.g., en-US, de-DE, ja-JP).

If a language is not specified, the map default to Neutral Ground Truth. This means that each map label will be displayed in its local language.

API Reference

For complete documentation of all properties, methods, and types:

TomTomMap API Reference →

Key Methods Summary

• setStyle(style, options?): Change map style dynamically
• getStyle(): Retrieve current style configuration
• addStyleChangeHandler(handler): Register style change callbacks
• mapLibreMap: Access underlying MapLibre instance
• mapReady: Check if map is fully loaded

Next Steps

• Modules Guide : Add functionality with modules
• Map Styles : Explore styling options
• User Interaction Events : Handle interactions
• Service Integration : Connect TomTom services