Map styles

Map Styles in the TomTom Maps SDK define the visual appearance and data presentation of maps. This guide covers TomTom’s built-in styles, style components, and customization options.

A map style consists of various layers and sources that determine how geographic features are rendered.

The SDK provides several pre-defined styles optimized for different use cases, along with the ability to customize styles by including additional layers or modifying existing ones.

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { type StandardStyleID, standardStyleIDs, TomTomMap } from '@tomtom-org/maps-sdk/map';
import './style.css';
import { API_KEY } from './config';
import { initTogglePanel } from './togglePanel';

TomTomConfig.instance.put({ apiKey: API_KEY, language: 'en-GB' });

const map = new TomTomMap({
    mapLibre: {
        container: 'sdk-map',
        zoom: 14,
        center: [-0.12621, 51.50394],
    },
});

const stylesSelector = document.querySelector('#ui-mapStyles') as HTMLSelectElement;
standardStyleIDs.forEach((id) => stylesSelector.add(new Option(id)));
stylesSelector.addEventListener('change', (event) =>
    map.setStyle((event.target as HTMLOptionElement).value as StandardStyleID),
);

initTogglePanel();

Built-in styles

Basic styles

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

3
// Light theme (default)
4
const map = new TomTomMap({
5
    mapLibre: {
6
        container: 'map'
7
    },
8
    style: 'monoLight'
9
});
10

11
// Dark theme
12
const map = new TomTomMap({
13
    mapLibre: {
14
        container: 'map'
15
    },
16
    style: 'monoDark'
17
});
18

19
// Satellite imagery with roads and labels
20
const map = new TomTomMap({
21
    mapLibre: {
22
        container: 'map'
23
    },
24
    style: 'satellite'
25
});

The full list of IDs is exported as standardStyleIDs: standardLight, standardDark, drivingLight, drivingDark, monoLight, monoDark and satellite.

Dynamic style switching

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

3
// Change style after map creation
4
map.setStyle('monoDark');
5
// ...
6
map.setStyle('drivingLight');

setStyle returns a promise that resolves once the new style has loaded and every SDK module has restored itself onto it. Awaiting it is optional, but it is the moment after which the map is safe to read and draw on again:

1
await map.setStyle('standardDark');
2
// map.mapReady is true again; routes, places and traffic are back on the new style

Keeping or dropping state

By default a style switch carries everything over: module data and configuration (routes, places, POI filters, traffic visibility…) and the style parts of the previous style (traffic, hillshade). Pass resetState: true for a clean switch instead:

1
// Carry everything over (default)
2
map.setStyle('standardDark');
3

4
// Clean switch: modules re-bind to the new style with default configuration and nothing shown,
5
// and only the style parts named in the new style are loaded
6
map.setStyle('standardDark', { resetState: true });

Both variants run the registered style change handlers (below); each handler learns which kind of switch it is from its context.resetState argument.

The map language is not SDK state, so neither variant touches it: it is re-applied to the new style either way, and only setLanguage changes it.

Passing the style that is already loaded runs the same lifecycle without reloading the style, so setStyle(currentStyle, { resetState: true }) is how you reset the SDK modules over the map you are already looking at.

Listening to style changes

Use addStyleChangeHandler to react when a style transition triggered by map.setStyle() begins or completes. This is the right hook for preserving custom layers, syncing UI state, or reinitializing anything that depends on the current style.

:::note This handler only fires for setStyle calls on TomTomMap. It does not fire on initial map construction. For lower-level style lifecycle hooks — such as reacting to the initial style load or to any style-related MapLibre event — use map.mapLibreMap.on('styledata', ...) directly. :::

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

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

5
const unsubscribe = map.addStyleChangeHandler({
6
    onStyleAboutToChange: (context) => {
7
        // Called before the style change begins — clean up anything tied to the current style
8
    },
9
    onStyleChanged: (context) => {
10
        // Called after the new style is fully loaded — restore state, re-add layers, update UI.
11
        // context.resetState tells you whether this is a clean switch (see above).
12
    },
13
});
14

15
// Later, when the handler's owner is torn down:
16
unsubscribe();

Both callbacks are optional. Use only the one(s) you need. Handlers run in registration order, after the SDK’s own modules have restored themselves.

Preserving custom MapLibre layers

Custom sources and layers added via map.mapLibreMap are removed when the style changes. Use onStyleAboutToChange to save their data and onStyleChanged to restore them:

1
import type { GeoJSONSource } from 'maplibre-gl';
2

3
let savedData: GeoJSON.FeatureCollection | null = null;
4

5
map.addStyleChangeHandler({
6
    onStyleAboutToChange: () => {
7
        const source = map.mapLibreMap.getSource('my-data') as GeoJSONSource | undefined;
8
        if (source) {
9
            savedData = source._data as GeoJSON.FeatureCollection;
10
        }
11
    },
12
    onStyleChanged: () => {
13
        if (savedData) {
14
            map.mapLibreMap.addSource('my-data', { type: 'geojson', data: savedData });
15
            map.mapLibreMap.addLayer({
16
                id: 'my-layer',
17
                type: 'circle',
18
                source: 'my-data',
19
                paint: { 'circle-radius': 6, 'circle-color': '#007cbf' },
20
            });
21
        }
22
    },
23
});

Updating UI based on the active style

1
map.addStyleChangeHandler({
2
    onStyleChanged: () => {
3
        const style = map.getStyle();
4
        const isDark = typeof style === 'string'
5
            ? style.toLowerCase().includes('dark')
6
            : style?.id?.toLowerCase().includes('dark') ?? false;
7
        document.body.classList.toggle('dark-mode', isDark);
8
    },
9
});

Async handlers

Both callbacks can be async. The SDK awaits each one before continuing: onStyleAboutToChange handlers finish before the new style is handed to MapLibre, and the promise returned by setStyle resolves only after the last onStyleChanged handler has finished.

1
map.addStyleChangeHandler({
2
    onStyleAboutToChange: async () => {
3
        await persistStateToServer(map.getStyle());
4
    },
5
    onStyleChanged: async () => {
6
        await restoreStateFromServer();
7
    },
8
});

Custom styles

A custom style (style: { type: 'custom', url } or { type: 'custom', json }) loads as-is. Once it has loaded, the SDK reads its light/dark theme from the style’s background colour, so overlays such as places and routes pick legible text colours on a dark custom style too. Declare lightDarkTheme: 'light' | 'dark' on the style to say it yourself, and the SDK takes it at its word rather than reading the background: worth doing when the canvas sits behind full-coverage imagery, or when its colour does not represent what the map ends up looking like. Either way, map.styleLightDarkTheme reports the theme in effect. Style-owned modules (traffic, hillshade) work on a custom style when it already ships the matching source; the SDK cannot add a style part to a custom style, and says so if you ask it to.

Available style parts

The map style includes multiple parts that come from different data sources:

• Base Map and POIs: Core geographic features and points of interest.
  • Included and visible by default with all styles.
  • Controlled by BaseMapModule and POIsModule.
• Traffic Incidents: Real-time traffic incident data.
  • Included in the style by default, but hidden upfront.
  • Can be optionally excluded from the style for performance.
  • Controlled by TrafficIncidentsModule.
• Traffic Flow: Live traffic flow information.
  • Included in the style by default, but hidden upfront.
  • Can be optionally excluded from the style for performance.
  • Controlled by TrafficFlowModule.
• Hillshade: Terrain elevation shading for enhanced topography.
  • Included in the style by default, but hidden upfront.
  • Can be optionally excluded from the style for performance.
  • Controlled by HillshadeModule.

1
// Common layer modules you can include or not:
2
include: [
3
    'trafficIncidents',  // Traffic incidents
4
    'trafficFlow',       // Traffic flow data
5
    'hillshade'          // Terrain shading
6
]

Map language

1
const map = new TomTomMap({
2
    mapLibre: {
3
        container: 'map'
4
    },
5
    style: 'monoLight',
6
    language: 'de-DE' // German labels
7
});

Set it once — here, or in the global configuration — and it holds for the life of the map. Every style arrives with local-language labels, so the SDK re-applies the language after each style load, whether or not the switch carries state over. map.setLanguage('nl-NL') changes it at runtime.

Related guides and examples

Core map setup

• Map Quickstart - Basic map creation and style configuration
• Base Map - Control fundamental map layer visibility
• About MapLibre - Understanding the underlying mapping technology

Advanced features

• Traffic Flow - Add real-time traffic data to your styles
• Traffic Incidents - Display traffic incidents with custom styling
• Hillshade - Add terrain elevation shading to your maps

Practical examples

• Reset State When Changing Style - Carry the map state across a style switch, or drop it
• Load Style Parts - Dynamic style component loading
• Map Language - Language switching and localization
• Default map - Simple style implementation

Integration and customization

• User Interaction Events - Handle style-related user interactions
• Places - Style integration with places data
• Routes - Route visualization with different map styles