Route styling

The Routing module draws routes in its own look. color, widthPreset and opacity style the whole route, waypoints.sizePreset and waypoints.label the waypoints, summaryBubbles the bubbles, and layers each layer. You can try them all on the route style playground. Styling knobs reach route layers only through the accent, which a route without a color defaults to, the label and halo colours its summary bubbles take, 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
    opacity: 0.7,            // the route lines and their outlines, 0 to 1
8
    waypoints: {
9
        sizePreset: 's',     // 's' | 'm' | 'l'
10
        sizeFactor: 1.5,     // multiplies the preset, 0.5 to 2
11
    },
12
});

• A factor multiplies its preset instead of replacing it, and is clamped to its range in routingKnobCatalogue, which knobEntryOf(routingKnobCatalogue, 'widthFactor') reads.
• opacity fades the route lines and their outlines, selected and deselected. Each section keeps its own sections.<type>.opacity, and the waypoints, bubbles and instruction lines stay opaque.
• 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

Summary bubbles

Each route carries a bubble with its duration, distance and traffic delay. summaryBubbles decides what it says, which routes carry one, where it sits, how it looks and at which zooms it appears. You can try each setting on the summary bubbles playground:

1
const routingModule = await RoutingModule.create(map, {
2
    summaryBubbles: {
3
        fields: ['duration', 'trafficDelay'], // drops the distance
4
        minZoom: 8,                           // hidden while the whole country is in view
5
        color: '#1A2024',                     // the bubble, deselected routes a shade darker
6
        label: { size: 14, typeface: 'serif' },
7
    },
8
});

• fields lists duration, distance, durationDifference and trafficDelay. The first field a route carries is in bold and the others follow it muted. The traffic delay takes its own line, and only on routes with a delay.
• durationDifference times each other route against the selected one, such as +6 min. The selected route shows none, and neither does a route whose duration rounds to the same minute.
• A bubble with nothing to say isn’t drawn. ['trafficDelay'] shows bubbles only on delayed routes, ['durationDifference'] only on the routes you can switch to, and [] shows none.
• By default, the bubble follows the map. Once a theme sets the labelHalo colour, the bubble takes it, lightened to stand off the land, and once it sets label, the text takes that. Without them, the bubble is white on a light style and dark grey on a dark one.
• The text takes whichever of dark or light reads on the bubble, including a color of your own, and label.color overrides the selected route’s text.
• label.size, label.opacity, label.typeface and label.customTypeface work as they do for waypoint labels.

Which routes, and where

Alternatives often share most of their way, so each bubble sits on its route’s longest distinct section, a stretch of road the route has to itself, where the other bubbles can’t hide it. routes picks which routes carry one, to keep them out of the way of a panel or popup of your own:

1
routingModule.updateConfig({
2
    summaryBubbles: {
3
        routes: 'alternatives',  // the selected route's trip is in your own panel
4
        fields: ['duration', 'durationDifference'],
5
    },
6
});

• The first route’s bubble sits halfway along its longest distinct section, and each next one takes whichever point a quarter, half or three quarters along its own is farthest from the bubbles before it. A route with no distinct section, or none as long as 5% of the route, uses its whole length.
• The routes of one calculateRoute call carry their sections.distinct, which the module reads. It compares the routes itself only when one lacks them, such as a route you built. Show one response’s routes, all of them: distinct sections found against other routes than those shown, such as a subset or the routes of two calls, can put a bubble on a road they share.
• routes is 'all' by default. 'selected' keeps the selected route’s bubble alone, and 'alternatives' every bubble but that one.
• The bubbles stay where they are when you select another route or change routes, so the one a user just clicked stays under their pointer. selectRoute updates the routes they show on and their duration differences.

Your own text

To write your own text, set label.title. A function receives each route’s summary and returns its text, again whenever another route is selected, so it can read routeState, and a route it returns an empty string for gets no bubble:

1
routingModule.updateConfig({
2
    summaryBubbles: {
3
        label: {
4
            title: (summary) => (summary.properties.routeIndex === 0 ? `Fastest, ${summary.properties.formattedDuration}` : ''),
5
        },
6
    },
7
});

• The text comes in plain, in the bubble’s font and colour. A MapLibre expression works too, such as ['get', 'formattedDuration'], and draws every bubble.
• RoutingModuleSerializableConfig keeps an expression title and leaves out a function one.

Layer overrides

layers is keyed by part (mainLines, waypoints, sections, …) and then by layer. Each entry is a partial MapLibre layer, and its paint and layout merge property by property onto the layer the rest of the config built. Section layers are in Route sections.

1
const routingModule = await RoutingModule.create(map, {
2
    widthPreset: 's',
3
    layers: {
4
        mainLines: {
5
            routeLine: { paint: { 'line-blur': 1 } } // keeps the 's' width, the colour and the opacity
6
        }
7
    }
8
});

• Name only the properties you change. The ones you leave out keep the values widthPreset, widthFactor, color and opacity set.
• Don’t spread defaultRoutingLayers into an entry. It holds the layers drawn with the default config, so its line-width replaces the one your widthPreset and widthFactor computed. Read it for the layer names and their default values.
• For the route’s opacity, set opacity, or sections.<type>.opacity for a section, rather than a line-opacity override.

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.
• The catalogue leaves out layers, beforeLayerConfig, the waypoint images and mapping, the title of waypoint and bubble labels, and their customTypeface, which take structured, MapLibre or function values. It leaves out events too.
• 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, opacity, waypoint size, waypoint label colour and clicked outline on knobs, and a toggle that hides it
• Route summary bubbles playground - What the bubbles say, which routes carry one, their colour, typeface and zooms on knobs, and a title of your own per route
• Route waypoints playground - Per-role pins, stop numbering, labels, hover growth, a category pin per stop and a finish image of your own
• React route planner - Summary bubbles on the alternatives alone, each timing its route against the selected one, and a click on one to pick it
• Map theme - A route following the accent of a theme