Route styling

The Routing module draws its routes in a look of its own: color and width for the whole route, waypoints.size and waypoints.label for the waypoints, or layers per layer, all live on the route style playground. No styling knob reaches route layers except the accent a route given no color defaults to, and the delay colours of its traffic sections.

Colour, width and waypoint size

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

const routingModule = await RoutingModule.create(map, {
    color: '#DF1B12',        // the route line, its outline (a darker shade) and the waypoint pins
    width: 'l',              // 's' | 'm' | 'l'
    widthFactor: 1.2,        // multiplies the preset, 0.5 to 2
    waypoints: {
        size: 's',           // 's' | 'm' | 'l'
        sizeFactor: 1.5,     // multiplies the preset, 0.5 to 2
    },
});

• A factor composes with its preset rather than replacing it, and is clamped to its range in routingKnobCatalogue, which knobEntryOf(routingKnobCatalogue, 'widthFactor') reads.
• The instruction arrows keep one size across the width presets and follow only widthFactor.
• The stop marks scale with their pins, preset and factor alike, and stay centred in the pin head at every zoom.
• The waypoint labels follow the map's light/dark theme, like the labels of places and geometries: dark text on a white halo on a light map, the two swapped on a dark one. waypoints.label sets their colour, halo and size, as label does for places. Pins per role, labels of your own and icons per waypoint are in Waypoints.

Leave color out and routes take the map's accent when a theme sets one, and the SDK's route blue otherwise:

const brandedRoutes = await RoutingModule.create(map, { color: '#DF1B12' }); // stays red through any theme
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.

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

Every setting as data

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

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

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

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

• A section type lists only the knobs it answers to: speedLimit takes only visible and sign, and 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> 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, the charging stop icons and title, 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: 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, charging stops, border crossings and section icons, the tunnel sign and the icons generated section types ask for lowest among them. A target puts them all beneath it, in that order.

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

• Each part keeps its own layers in order wherever it goes, and applyConfig or updateConfig restacks 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 settles which symbols they give way to, wherever the parts are.

Charging stop icons

Long-distance EV routes place a charging stop at the end of each leg. Supply your own sprites with chargingStops.icon.customIcons, then pick one per stop with mapping:

const routingModule = await RoutingModule.create(map, {
  chargingStops: {
    icon: {
      customIcons: [
        { id: 'slow-charger', image: chargerSlowSVG },
        { id: 'fast-charger', image: chargerFastSVG, offsetX: 0, offsetY: -10 }
      ],
      mapping: {
        basedOn: 'chargingSpeed',
        value: { slow: 'slow-charger', regular: 'slow-charger', fast: 'fast-charger', 'ultra-fast': 'fast-charger' }
      }
    }
  }
});

• mapping also takes { basedOn: 'custom', fn: (stop) => spriteID }, and works without customIcons to point at sprites the style already ships.
• offsetX / offsetY (pixels) shift an icon from its coordinate, for icons whose visual tip is not their bottom: positive offsetX moves right, positive offsetY down. They apply only to a customIcons entry that also provides an image.

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
• Custom charging stops - Charging stop icons of your own, picked per stop