The routing module's events, in one interface.
events itself covers every route feature and the module's lifecycle events. Each named scope
below covers one part of a route, and you can narrow any of them further with where().
routing.events.mainLines.on('click', (route) => { ... });
routing.events.waypoints.on('hover', (waypoint) => { ... });
// Only the selected route's tunnels, with their own hover cursor:
routing.events.tunnels
.where((section) => section.properties.routeState === 'selected', { cursorOnHover: 'help' })
.on('click', showTunnel);
const unsub = routing.events.on('config-change', (config) => { ... });
routing.events.on('shown-features', (features) => {
if ('routes' in features) { ... }
});
unsub();
The MapLibre source and layer IDs of all sources this module creates and manages.
A record mapping each source name to its MapLibre source ID and an array of the IDs of that source's layers.
Applies a configuration to this module.
The module updates its behaviour and appearance to match. It stores the configuration and reapplies it automatically when the map style changes.
The configuration to apply. Pass undefined to reset it to the default values.
The given configuration replaces the current one rather than being merged into it. To change one part of it, use updateConfig.
Use it for settings your code writes. It takes every setting, typed, including the ones no knob covers (layer specs, callbacks, MapLibre expressions), and checks no value at run time. For settings held as data, from a control, storage or a language model, use setKnobs.
// Apply a new configuration
myModule.applyConfig({ visible: true, color: '#E63312' });
// Reset to default configuration
myModule.applyConfig(undefined);
Takes the event state off one of the shown features.
Takes the given event states, or all of them, off the shown features.
Optionaloptions: ClearEventStatesOptionsClears any previously shown routes from the map.
Clears any previously shown waypoints from the map. If nothing was shown before, nothing happens.
Returns a shallow copy of the current module configuration, or undefined if none is applied.
A shallow copy of the current configuration, or undefined. It is a copy so that you
can't modify the internal state by accident.
Only the top-level properties are copied. Nested objects and arrays still reference the original configuration. This is enough for most use cases, but keep it in mind with complex configurations.
// 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
Returns the ids of the shown features that have an event state, by state.
The read side of setEventState and clearEventStates, reflecting 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 setEventState.
Returns the map style layer the route lines render under, or undefined when they are on top of the stack.
Use it to render extra layers just above the route lines but not on top of everything else. It
follows beforeLayerConfig, and can differ with the loaded style or its version.
Returns the currently shown routes and waypoints.
An object containing all currently displayed routing data.
Returns what each source draws, as prepared for display from what showRoutes() and
showWaypoints() were given.
Returned data:
mainLines: Main route lines (selected and alternative)waypoints: Route waypoints (start, stops, finish)incidents: Traffic incidents on routesferries: Ferry sectionstollRoads: Sections that cost money to drive, of the tollRoad section typetunnels: Tunnel sectionsvehicleRestricted: Vehicle-restricted sections<type>Sections: Each other drawn section type, such as urbanSectionsinstructionLines: Turn-by-turn instruction linesinstructionArrows: Instruction arrow markerssummaryBubbles: Route summary popupscountryCrossings: Border crossings along the routesectionFocus: The sections setSectionFocus() ringsWhether 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.
Resets this module's configuration to its default values.
It clears any applied configuration and restores the module to its initial state, the same
as calling applyConfig(undefined).
The module then behaves as if no configuration was ever applied. Any custom settings, styling or behaviour changes are replaced with default values.
// Apply some configuration
myModule.applyConfig({ visible: true, color: '#E63312' });
// Later, reset to defaults
myModule.resetConfig();
Changes which route appears as selected.
Zero-based position of the route to select among the shown ones. A route's
properties.index is its index in the routing response, which is that position only when you
show every route of the response.
The selected route appears more prominent, thicker and brighter, and the previously selected
one takes the deselected style. The sections, guidance and other route features update with it,
and the summary bubbles' duration differences and titles are worked out again. The click event
state of the route lines and summary bubbles is cleared, since the selection now marks the route.
Show the routes with showRoutes first, and pass an index within their range.
Puts an event state on one of the shown features, as a user interaction would.
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, but not a new
show, a clear or a setStyle with resetState.
Rings the given sections of the shown routes, or clears the ring with null.
The id of each section to focus, from any route shown and of any type,
drawn or not. An id no shown section carries is skipped.
The ring runs on both sides of the route, clear of the widest line it draws, whether its
hovered outline or a section, so the route and every section along it stay in sight. A
deselected route's ring sits under the selected route. RouteHighlightConfig section
styles it. Each call replaces the focus, and showRoutes clears it.
Shows or hides everything the module draws.
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.
Displays the given routes on the map.
This method doesn't show waypoints. It draws route lines, not start, stop or destination markers. To show them, call showWaypoints separately.
This method:
It draws:
tollRoad) and vehicle-restricted sections, speed-limit signs, and
the other section types sections showsShow a route (no waypoint markers):
await routing.showRoutes(routes);
// Waypoint markers are NOT shown — call showWaypoints() to add them
Displays waypoint markers (start, stop, and destination pins) on the map.
An array of planning waypoints or a Waypoints FeatureCollection.
showRoutes doesn't show waypoint markers, so call this method separately.
Pass every location the route is calculated through, so that its pin carries its role and stop mark and the route's events reach it. Show a place the user is still choosing among as a PlacesModule marker instead, and clear it there once it joins the route. Each pin draws as RoutingModuleConfig.waypoints sets, including the per-role pins and an icon mapped from the waypoint's data.
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 one that was there. The result is applied with
applyConfig. This works the same on every module, whatever its applyConfig does with
a whole configuration.
The properties to change.
Use it for settings your code writes, as applyConfig: typed, and not checked at run time. To change nested values and keep the ones beside them, or to set values held as data, use setKnobs, which reaches each by its path and checks it.
routing.applyConfig({ displayUnits: { distance: { type: 'imperial_us' } }, color: '#0a3653' });
routing.updateConfig({ color: '#c2185b' }); // displayUnits stays imperial
applyConfig to apply a whole configuration
StaticcreateWaits until the map is ready, then creates an instance of the module.
Optionalconfig: RoutingModuleConfigRoutingModule owns the sources, layers and images it adds, all suffixed per instance. So
every call returns a new, independent instance, and you can stack several of them on one map.
routingKnobCatalogue lists every plain-valued display setting, and RoutingModuleConfig.layers the MapLibre overrides for what they can't express.
The map module that displays and manages routes.
It draws route lines, alternative routes, turn-by-turn guidance and waypoints, and works with the TomTom Routing API.
Remarks
Features:
Common use cases:
events.waypointsandevents.mainLinesand plans nothing: you callcalculateRouteandshowRouteswith the new waypoints.Example
Example
Drag a waypoint to move its stop, then plan again:
See
Routes Guide