Class RoutingModule

Map module for displaying and managing route visualizations.

The RoutingModule provides comprehensive functionality for displaying routes on the map, including route lines, alternative routes, turn-by-turn guidance, and waypoints. It integrates seamlessly with the TomTom Routing API.

Remarks

Features:

Display route lines with customizable styling
Show alternative routes with different styling
Waypoint pins per role — origin, numbered or lettered stops, destination — with hover and click events
Turn-by-turn guidance instructions
Route section highlighting
Distance and duration information
Support for multiple routes simultaneously

Common Use Cases:

Turn-by-turn navigation displays
Route planning and comparison
Multi-stop route optimization
Interactive route editing
Fleet management route visualization

Example

// Create the module
const routingModule = await RoutingModule.create(map, {
  displayUnits: {
    distance: { type: 'metric' }
  }
});

// Calculate and display a route
const result = await calculateRoute({
  key: 'your-api-key',
  locations: [
    [4.9041, 52.3676],  // Amsterdam
    [4.4777, 51.9244]   // Rotterdam
  ],
  routeOptions: {
    travelMode: 'car',
    routeType: 'fastest'
  }
});

await routingModule.showRoutes(result);

See

Routing Guide

Hierarchy (View Summary)

AbstractDataOwnedMapModule<RoutingSourcesWithLayers, RoutingModuleConfig>
- RoutingModule

Accessors

events

get events(): RoutingEvents

Unified events interface for the routing module.

events itself covers every route feature and the module's lifecycle events; the named scopes below cover one part of a route each, and every one of them can be narrowed further with where().

routing.events.mainLines.on('click', (route) => { ... });
routing.events.waypoints.on('hover', (waypoint) => { ... });

// Only the long tunnels, with their own hover cursor:
routing.events.tunnels
    .where((section) => section.properties.lengthInMeters > 500, { cursorOnHover: 'help' })
    .on('click', showTunnel);

const unsub = routing.events.on('config-change', (config) => { ... });
routing.events.on('shown-features', (features) => {
  if ('routes' in features) { ... }
});
unsub();

Returns RoutingEvents

sourceAndLayerIDs

get sourceAndLayerIDs(): Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>
Gets the source and layer identifiers for all sources managed by this module.

This property provides access to the MapLibre source and layer IDs that were created and are managed by this module. These IDs can be used to interact directly with MapLibre's API or to identify which layers belong to this module.

Returns Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>
A record mapping each source name to its corresponding source ID and layer IDs. Each entry contains the MapLibre source identifier and an array of layer identifiers associated with that source.
Remarks
The returned IDs are useful when you need to:
- Directly manipulate layers using MapLibre's native API
- Identify which layers on the map belong to this module
- Set layer ordering or positioning relative to other layers
- Access source or layer properties through MapLibre methods
Example
```
const ids = myModule.sourceAndLayerIDs;
console.log(ids);
// {
//   mySource: {
//     sourceID: 'my-source-id',
//     layerIDs: ['layer-1', 'layer-2']
//   }
// }

// Use with MapLibre API
const map = myModule.mapLibreMap;
ids.mySource.layerIDs.forEach(layerId => {
  map.setLayoutProperty(layerId, 'visibility', 'visible');
});
```
Inherited from AbstractDataOwnedMapModule.sourceAndLayerIDs

Methods

applyConfig

applyConfig(config: RoutingModuleConfig | undefined): void
Applies a configuration to this module.

This method updates the module's behavior and appearance based on the provided configuration. The configuration is stored internally and will be automatically reapplied if the map style changes.
Parameters
- config: RoutingModuleConfig | undefined
  The configuration object to apply to the module. Pass undefined to reset the configuration to default values.
Returns void
Remarks
When a configuration is applied, the module updates its visual representation and behavior accordingly. The configuration persists across map style changes, ensuring consistent module behavior even when the map's base style is modified.

The given configuration replaces the current one rather than being merged into it. To change one part of it, use updateConfig.
Example
```
// Apply a new configuration
myModule.applyConfig({ visible: true, color: '#E63312' });

// Reset to default configuration
myModule.applyConfig(undefined);
```
See
- resetConfig for a convenience method to reset configuration
- getConfig to retrieve the current configuration
Inherited from AbstractDataOwnedMapModule.applyConfig

cleanEventState

cleanEventState(options: CleanEventStateOptions): void
Takes the event state off one of the shown features.
Parameters
- options: CleanEventStateOptions
Returns void
Example
```
module.cleanEventState({ id: feature.id });
```
Inherited from AbstractDataOwnedMapModule.cleanEventState

cleanEventStates

cleanEventStates(options?: CleanEventStatesOptions): void
Takes the given event states, or all of them, off the shown features.
Parameters
- Optionaloptions: CleanEventStatesOptions
Returns void
Example
```
module.cleanEventStates(); // every state
module.cleanEventStates({ states: ['hover'] }); // hovers only, selections stay
```
Inherited from AbstractDataOwnedMapModule.cleanEventStates

clearRoutes

clearRoutes(): Promise<void>
Clears any previously shown routes from the map.

Returns Promise<void>
Remarks
- Clears all route-related layers (lines, sections, guidance, summaries)
- Does NOT clear waypoints (use clearWaypoints)
- Module remains initialized and ready for new routes
Example
```
await routing.clearRoutes();
```

clearWaypoints

clearWaypoints(): Promise<void>

Clears any previously shown waypoints from the map. If nothing was shown before, nothing happens.

Returns Promise<void>

getConfig

getConfig(): NonNullable<RoutingModuleConfig> | undefined
Retrieves a copy of the current module configuration.

This method returns a shallow copy of the configuration object that is currently applied to the module. If no configuration has been applied, it returns undefined.

Returns NonNullable<RoutingModuleConfig> | undefined
A shallow copy of the current configuration object, or undefined if no configuration is currently applied. The returned object is a copy to prevent unintended modifications to the internal state.
Remarks
The returned configuration object is a shallow copy, which means that while the top-level properties are copied, any nested objects or arrays are still referenced from the original configuration. This is sufficient for most use cases but should be kept in mind when dealing with complex configurations.
Example
```
// Apply a configuration
myModule.applyConfig({ visible: true, color: '#E63312' });

// Later, retrieve the current configuration
const currentConfig = myModule.getConfig();
console.log(currentConfig); // { visible: true, color: '#E63312' }

// When no config is applied
myModule.resetConfig();
console.log(myModule.getConfig()); // undefined
```
See
- applyConfig to modify the configuration
- resetConfig to clear the configuration
Inherited from AbstractDataOwnedMapModule.getConfig

getEventStates

getEventStates(): EventStateIds
Returns the ids of the shown features that have an event state, by state.

Returns EventStateIds
Remarks
The read side of putEventState and cleanEventStates: it reflects those and the states user interactions put. The ids are those getShown() and the event handlers hand back, so each can go straight back into putEventState.
Example
```
// Keep a list in sync with the selected feature
const { click: [selectedID] = [] } = module.getEventStates();

// Is this feature hovered?
const hovered = module.getEventStates().hover?.includes(feature.id) ?? false;
```
Inherited from AbstractDataOwnedMapModule.getEventStates

getLayerToRenderLinesUnder

getLayerToRenderLinesUnder(): string | undefined
Returns the map style layer under which route lines are rendered, or undefined when they are on top of the stack.
- Useful if you want to render extra layers just above the route ones but not on top of everything else.
- Follows beforeLayerConfig, and might differ depending on the loaded style/version.
Returns string | undefined

getShown

getShown(): {
    carpoolSections: RouteSections
    | undefined;
    carTrainSections: RouteSections | undefined;
    chargingStops: DisplayChargingStops;
    countryCrossings: DisplayCountryCrossings;
    ferries: RouteSections;
    importantRoadStretchSections: RouteSections | undefined;
    incidents: RouteSections<DisplayTrafficSectionProps>;
    instructionArrows: DisplayInstructionArrows;
    instructionLines: DisplayInstructions;
    lowEmissionZoneSections: RouteSections | undefined;
    mainLines: Routes<DisplayRouteProps>;
    motorwaySections: RouteSections | undefined;
    pedestrianSections: RouteSections | undefined;
    speedLimitSections: RouteSections | undefined;
    summaryBubbles: DisplayRouteSummaries;
    tollRoads: RouteSections;
    tollVignetteSections: RouteSections | undefined;
    tunnels: RouteSections;
    unpavedSections: RouteSections | undefined;
    urbanSections: RouteSections | undefined;
    vehicleRestricted: RouteSections;
    waypoints: Waypoints<WaypointDisplayProps>;
}
Returns the currently shown routes and waypoints.

Returns {
    carpoolSections: RouteSections | undefined;
    carTrainSections: RouteSections | undefined;
    chargingStops: DisplayChargingStops;
    countryCrossings: DisplayCountryCrossings;
    ferries: RouteSections;
    importantRoadStretchSections: RouteSections | undefined;
    incidents: RouteSections<DisplayTrafficSectionProps>;
    instructionArrows: DisplayInstructionArrows;
    instructionLines: DisplayInstructions;
    lowEmissionZoneSections: RouteSections | undefined;
    mainLines: Routes<DisplayRouteProps>;
    motorwaySections: RouteSections | undefined;
    pedestrianSections: RouteSections | undefined;
    speedLimitSections: RouteSections | undefined;
    summaryBubbles: DisplayRouteSummaries;
    tollRoads: RouteSections;
    tollVignetteSections: RouteSections | undefined;
    tunnels: RouteSections;
    unpavedSections: RouteSections | undefined;
    urbanSections: RouteSections | undefined;
    vehicleRestricted: RouteSections;
    waypoints: Waypoints<WaypointDisplayProps>;
}
An object containing all currently displayed routing data.
Remarks
Returns the exact data that was passed to the showRoutes() and showWaypoints() methods.

Returned Data:
- mainLines: Main route lines (selected and alternative)
- waypoints: Route waypoints (start, stops, finish)
- incidents: Traffic incidents on routes
- ferries: Ferry sections
- chargingStops: EV charging stations
- tollRoads: Sections that cost money to drive — the tollRoad section type
- tunnels: Tunnel sections
- vehicleRestricted: Vehicle-restricted sections
- instructionLines: Turn-by-turn instruction lines
- instructionArrows: Instruction arrow markers
- summaryBubbles: Route summary popups
- countryCrossings: Border crossings along the route
Example
```
const shown = routingModule.getShown();
console.log(`Showing ${shown.mainLines.features.length} routes`);
console.log(`Showing ${shown.waypoints.features.length} waypoints`);
console.log(`Showing ${shown.chargingStops.features.length} charging stops`);
```
Example
Check if any routes are displayed:
```
const shown = routingModule.getShown();
if (shown.mainLines.features.length > 0) {
  console.log('Routes are displayed');
} else {
  console.log('No routes displayed');
}
```

isVisible

isVisible(): boolean

Whether the module is set to be shown: its visible setting, true unless set. A shown module with nothing shown draws nothing; getShown() returns what is shown.

Returns boolean

Inherited from AbstractDataOwnedMapModule.isVisible

putEventState

putEventState(options: PutEventStateOptions): void
Puts an event state on one of the shown features, as a user interaction would.
Parameters
- options: PutEventStateOptions
Returns void
Remarks
The state is what the module's own layers draw (place pins and entry points, route outlines, geometries, details-module incidents, area-analytics cells), what layers of yours read with ['get', 'eventState'], and what getEventStates returns. It lasts as long as the shown feature does: through setVisible, style and configuration changes, not through a new show, a clear or a setStyle with resetState.
Example
```
// Select a feature from a list, as a click would
module.putEventState({ id: feature.id, state: 'click' });

// Hover a second one without taking the hover off the first
module.putEventState({ index: 2, state: 'hover', mode: 'add' });
```
Inherited from AbstractDataOwnedMapModule.putEventState

resetConfig

resetConfig(): void
Resets the configuration of this module to its default values.

This is a convenience method that clears any previously applied configuration and restores the module to its initial state. This is equivalent to calling applyConfig(undefined).

Returns void
Remarks
After calling this method, the module will behave as if no configuration was ever applied. Any custom settings, styling, or behavior modifications will be removed and replaced with default values.
Example
```
// Apply some configuration
myModule.applyConfig({ visible: true, color: '#E63312' });

// Later, reset to defaults
myModule.resetConfig();
```
See
- applyConfig to apply a new configuration
- getConfig to retrieve the current configuration before resetting
Inherited from AbstractDataOwnedMapModule.resetConfig

selectRoute

selectRoute(index: number): Promise<void>
Changes which route appears as selected.
Parameters
- index: number
  Zero-based index of the route to select.
Returns Promise<void>
Remarks
Visual Changes:
- Selected route appears more prominent (thicker, brighter)
- Previously selected route becomes deselected style
- Updates all route-related features (sections, guidance)
Requirements:
- Route must already be displayed via showRoutes
- Index must be within range of displayed routes
Example
```
// Show multiple routes
await routingModule.showRoutes(routes);

// User clicks alternative route
await routingModule.selectRoute(1);

// Switch back to first route
await routingModule.selectRoute(0);
```

setVisible

setVisible(visible: boolean): void
Shows or hides everything the module draws.
Parameters
- visible: boolean
Returns void
Remarks
Stored as visible in the configuration. Showing and clearing data never change it: a hidden module keeps its data, through style changes too, and draws it again on setVisible(true).

Showing leaves hidden what the configuration turns off: a route section type that is off, the layers a place marker type does not use.
Example
```
module.setVisible(false);
await module.show(data); // stays hidden
module.setVisible(true);
```
Inherited from AbstractDataOwnedMapModule.setVisible

showRoutes

showRoutes(routes: Route | Routes, options?: ShowRoutesOptions): Promise<void>
Displays the given routes on the map.
Parameters
- routes: Route | Routes
  Route data from Routing API or custom routes.
- Optionaloptions: ShowRoutesOptions
  Optional configuration for route selection and display.
  - selectedIndex
    
    Index of the route to display as selected (default: 0).
Returns Promise<void>
Remarks
Waypoints are NOT shown by this method. Route lines are drawn but start/stop/destination markers are not. To display waypoint markers, call showWaypoints separately.

Behavior:
- Replaces any previously shown routes
- Shows all route-related features: lines, sections, summaries, guidance
- First route is selected by default (appears more prominent)
Route Features:
- Main route lines (selected and deselected styles)
- Traffic sections with delays
- Ferry, tunnel, and charged-road (tollRoad) sections
- EV charging stations (for EV routes)
- Turn-by-turn instruction lines and arrows
- Summary bubbles with distance/time/traffic info
Example
Show a route (no waypoint markers):
```
await routing.showRoutes(response.routes);
// Waypoint markers are NOT shown — call showWaypoints() to add them
```
Example
Show routes and waypoint markers:
```
const locations = [[4.9, 52.4], [4.5, 51.9]];
const response = await calculateRoute({ locations });
await routing.showRoutes(response.routes);
await routing.showWaypoints(locations); // Show start/destination markers separately
```
Example
Show multiple routes with specific selection:
```
await routing.showRoutes(response.routes, { selectedIndex: 1 });
```

showWaypoints

showWaypoints(waypoints: PlanningWaypoint[] | Waypoints): Promise<void>
Displays waypoint markers (start, stop, and destination pins) on the map.
Parameters
- waypoints: PlanningWaypoint[] | Waypoints
  An array of planning waypoints or a Waypoints FeatureCollection.
Returns Promise<void>
Remarks
Waypoint markers are not shown by showRoutes — this method must be called separately to display them.

Every location the route is calculated through belongs here, so that its pin carries its role and stop mark and the route's events reach it. A place the user is still choosing among is a PlacesModule marker: clear it there once it joins the route. Each pin is drawn as RoutingModuleConfig.waypoints sets, the per-role pins and an icon mapped from the waypoint's data included.
Example
Show routes and then waypoints:
```
const locations = [[4.9041, 52.3676], [4.4777, 51.9244]];
const response = await calculateRoute({ locations });
await routingModule.showRoutes(response.routes);
await routingModule.showWaypoints(locations); // Must be called separately
```

updateConfig

updateConfig(partial: Partial<NonNullable<CFG>>): void
Changes part of the configuration and keeps the rest.

The given properties are laid over the current configuration — one level deep, so a nested object you pass replaces the nested object that was there — and the result is applied with applyConfig. This is the same on every module, whatever its applyConfig does with a whole configuration.
Parameters
- partial: Partial<NonNullable<CFG>>
  The properties to change.
Returns void
Example
```
routing.applyConfig({ displayUnits: { distance: { type: 'imperial_us' } }, color: '#0a3653' });
routing.updateConfig({ color: '#c2185b' }); // displayUnits stays imperial
```
See
applyConfig to apply a whole configuration
Inherited from AbstractDataOwnedMapModule.updateConfig

`Protected`waitUntilModuleReady

waitUntilModuleReady(): Promise<void>

Returns Promise<void>

Inherited from AbstractDataOwnedMapModule.waitUntilModuleReady

`Static`create

create(
tomtomMap: TomTomMap,
config?: RoutingModuleConfig,
): Promise<RoutingModule>
Make sure the map is ready before create an instance of the module and any other interaction with the map
Parameters
- tomtomMap: TomTomMap
  The TomTomMap instance.
- Optionalconfig: RoutingModuleConfig
  The module optional configuration
Returns Promise<RoutingModule>
Returns a promise with a new instance of this module
Remarks
Instances: RoutingModule owns the sources, layers and images it adds, all suffixed per instance. Every call therefore returns a new, independent instance, and stacking several of them on one map is a supported thing to do.

Configuration Options: routingKnobCatalogue lists every plain-valued display setting; layers takes complete MapLibre layer specs.

Default Styling: If no custom layers are provided, uses defaultRoutingLayers.
Example
Default initialization:
```
const routingModule = await RoutingModule.create(map);
```
Example
With custom configuration:
```
const routingModule = await RoutingModule.create(map, {
  displayUnits: { distance: { type: 'imperial_us' } },
  waypoints: {
    entryPoints: 'main-when-available'
  }
});
```

Class RoutingModule

Remarks

Example

See

Hierarchy (View Summary)

Index

Accessors

Methods

Accessors

events

Returns RoutingEvents

sourceAndLayerIDs

Returns Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>

Remarks

Example

Methods

applyConfig

Parameters

Returns void

Remarks

Example

See

cleanEventState

Parameters

Returns void

Example

cleanEventStates

Parameters

Returns void

Example

clearRoutes

Returns Promise<void>

Remarks

Example

clearWaypoints

Returns Promise<void>

getConfig

Returns NonNullable<RoutingModuleConfig> | undefined

Remarks

Example

See

getEventStates

Returns EventStateIds

Remarks

Example

getLayerToRenderLinesUnder

Returns string | undefined

getShown

Remarks

Example

Example

isVisible

Returns boolean

putEventState

Parameters

Returns void

Remarks

Example

resetConfig

Returns void

Remarks

Example

See

selectRoute

Parameters

Returns Promise<void>

Remarks

Example

setVisible

Parameters

Returns void

Remarks

Example

showRoutes

Parameters

selectedIndex

Returns Promise<void>

Remarks

Example

Example

`Protected`waitUntilModuleReady

`Static`create