Route styling

The Routing module draws routes in its own look, with color and widthPreset for the whole route, waypoints.sizePreset and waypoints.label for the waypoints, or layers per layer, all live on the route style playground. Styling knobs reach route layers only through the accent, which a route without a color defaults to, and the delay colours of its traffic sections.

Colour, width and waypoint size

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

3
const routingModule = await RoutingModule.create(map, {
4
    color: '#DF1B12',        // the route line, its outline (a darker shade) and the waypoint pins
5
    widthPreset: 'l',        // 's' | 'm' | 'l'
6
    widthFactor: 1.2,        // multiplies the preset, 0.5 to 2
7
    waypoints: {
8
        sizePreset: 's',     // 's' | 'm' | 'l'
9
        sizeFactor: 1.5,     // multiplies the preset, 0.5 to 2
10
    },
11
});

• A factor multiplies its preset instead of replacing it, and is clamped to its range in routingKnobCatalogue, which knobEntryOf(routingKnobCatalogue, 'widthFactor') reads.
• The instruction arrows keep one size whatever the widthPreset, and follow only widthFactor.
• The stop marks scale with their pins, by preset and factor, and stay centred in the pin head at every zoom.
• The waypoint labels follow the map’s light or dark theme, like the labels of places and geometries, with dark text on a white halo on a light map and the reverse on a dark one. waypoints.label sets their colour, halo and size, as label does for places. Waypoints covers pins per role, your own labels and icons per waypoint.

Without a color, routes take the map’s accent when a theme sets one, or the SDK’s route blue otherwise:

1
const brandedRoutes = await RoutingModule.create(map, { color: '#DF1B12' }); // stays red through any theme
2
const themedRoutes = await RoutingModule.create(map); // follows map.mapColors.accent

Layer overrides

layers is keyed by part (mainLines, waypoints, sections, …) and then by layer. Each entry’s partial paint and layout merge onto the SDK’s own. Section layers are in Route sections.

1
const routingModule = await RoutingModule.create(map, {
2
    layers: {
3
        mainLines: {
4
            routeLine: { paint: { 'line-color': '#FF0000', 'line-width': 6 } }
5
        }
6
    }
7
});

Every setting as data

routingKnobCatalogue lists every plain-valued display setting of the module with its kind, its range or options, and its default where one value holds everywhere. Each id is the setting’s path in the config, so a UI can build its controls from it without a loaded map:

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

3
const tunnelKnobs = routingKnobCatalogue.filter(({ id }) => id.startsWith('sections.tunnel.'));
4
// [{ id: 'sections.tunnel.visible', kind: 'toggle', description: '…', default: true }, …,
5
//  { id: 'sections.tunnel.style', kind: 'enum', description: '…', options: ['halo', 'inline'], default: 'inline' }, …]

The route-wide knobs come first, then each section type’s knobs, where <type> stands for any of drawnSectionTypes:

• A section type lists only the knobs it supports. speedLimit takes only visible and sign. traffic, which colours its line by delay, has no color, pattern or icon entry.
• routingKnobIds lists the ids in catalogue order. RoutingKnobId is their union, and RoutingKnobValueOf<ID> is the plain value one takes.
• The unit labels after distances and durations are text entries with no default. A displayUnits knob left unset takes its value from the global configuration.
• Not in it: layers, beforeLayerConfig, and the waypoint images, mapping and title, which take structured, MapLibre or function values, and events.
• Its entries share their shape, KnobEntry, with every module’s catalogue.

Layer positioning

By default, the route lines sit below the map’s labels and the route icons above them. beforeLayerConfig moves them. It takes one target for the whole route ('top' or a key of mapStyleLayerIDs), or a record keyed by part, plus all for the parts it leaves out:

• mainLines - The route lines, and every section line drawn with them.
• instructionLines - The guidance lines and their arrows, above the route lines by default.
• icons - Waypoints, summary bubbles, border crossings and section icons. The tunnel sign and icons requested by generated section types sit lowest. A target puts them all beneath it in that order.

1
// Route lines under the road network; instruction lines and icons stay where they are
2
routingModule.updateConfig({ beforeLayerConfig: { mainLines: 'lowestRoadLine' } });

• Each part keeps its own layers in order wherever it goes. applyConfig and updateConfig restack them at runtime.
• A target the style lacks (the satellite style has no lowestRoadLine) puts the part on top.
• getLayerToRenderLinesUnder() follows mainLines, and returns undefined when the lines are on top.
• The speed limit signs are not a part. Their sign.priority decides which symbols they give way to, wherever the parts are.

Related guides and examples

Related guides

• Routing module - Showing routes and waypoints, events and shown data
• Route sections - The overlays drawn per stretch of road, on the same set of knobs
• Map modules - The knob kinds every catalogue shares

Related examples

• Route style playground - The route’s colour, width, waypoint size, waypoint label colour and clicked outline on knobs, and a toggle that hides it
• Route waypoints playground - Per-role pins, stop numbering, labels, hover growth, a category pin per stop and a finish image of your own
• Map theme - A route following the accent of a theme