Route sections

The Routing module’s showRoutes() draws an overlay for each stretch of road the response describes, such as urban stretches, motorways, low-emission zones, tunnels, ferries, traffic jams and toll roads. You configure each under sections, keyed by section type, with one set of knobs, each type taking the ones it can honour. The response carries only the types asked for in sectionTypes.

1
const routingModule = await RoutingModule.create(map, {
2
    sections: {
3
        urban: { visible: true },                                            // draw a type nothing draws by default
4
        lowEmissionZone: { color: '#1B7A43', opacity: 0.8 },                 // deepen the green of one that is
5
        tunnel: { color: '#402060', style: 'halo' },                         // restyle one that is drawn already
6
        tollRoad: { icon: { image: 'poi-toll_plaza', placement: 'along' } },  // put an icon on another
7
        traffic: { visible: false }                                          // and drop one
8
    }
9
});

Which sections draw by default

A type draws by default when its stretches are sparse along a route and consequential for the driver, such as money to pay, a permit to hold, a road the vehicle may not use, or the vehicle going onto a train.

• carTrain, ferry, lowEmissionZone, tollRoad, tollVignette, traffic, tunnel and vehicleRestricted draw by default. { visible: false } switches one off.
• speedLimit draws by default too, although it runs nearly a route’s whole length. It posts a sign per section instead of banding the route (below).
• carpool, importantRoadStretch, motorway, pedestrian, unpaved and urban are opt-in. { visible: true } switches one on. motorway and urban run nearly a route’s whole length, so a band for them buries the route line and says nothing the base map does not.
• sectionDrawsByDefault(type) reports which group a type is in, for a UI that shows the types as switches. Reading the map can’t tell you. A route with no ferry sections draws no ferry layer, so an absent layer looks the same as a type switched off.

Section knobs

style sets both the layer order and the width, because neither reads as intended without the other:

• halo puts the section beneath the route’s lines and wider than its outline, as a band hugging the route, which keeps its colour. It is the default for tollRoad and the nine generated types that band the route, so a low-emission zone reads as a green outline around it.
• inline puts the section over the route line at the route’s own width, so the route takes the section’s colour along that stretch. It is the default for ferry, traffic, tunnel and vehicleRestricted, which is why a route goes grey through a tunnel.
• applyConfig can switch a type’s style at runtime, because it restacks the layers.

The knobs a type takes are part of its TypeScript type:

• traffic colours its line by magnitudeOfDelay and takes its icons from the incident data. So sections.traffic.color does not compile, instead of compiling and drawing nothing.
• speedLimit draws no line, so it takes visible and sign and none of the line knobs.
• sectionSupportsKnob(type, knob) answers the same at runtime, for a UI that builds controls per type. It narrows type so the knob’s id compiles from it:

1
if (sectionSupportsKnob(type, 'sign')) {
2
    const { default: minZoom } = knobEntryOf(routingKnobCatalogue, `sections.${type}.sign.minZoom`);
3
}

The types are carpool, carTrain, ferry, importantRoadStretch, lowEmissionZone, motorway, pedestrian, speedLimit, tollRoad, tollVignette, traffic, tunnel, unpaved, urban and vehicleRestricted. Each one is live on the route sections playground.

Layer overrides

The full layer spec is under layers.sections, keyed by the same types. A generated type’s layer id comes from its name, so routeSectionMotorwayLine draws motorway and routeSectionSpeedLimitSign draws speedLimit:

1
const routingModule = await RoutingModule.create(map, {
2
    layers: {
3
        sections: {
4
            motorway: {
5
                routeSectionMotorwayLine: {
6
                    paint: { 'line-color': '#1F6FB2', 'line-dasharray': [2, 1] }
7
                }
8
            },
9
            tunnel: {
10
                routeTunnelLine: { paint: { 'line-blur': 2 } }
11
            }
12
        }
13
    }
14
});

A traffic section takes the colour of its delay (minor, moderate or major). Those colours follow the map’s incident colour knobs, as Borrowed looks describes.

Tunnels and closed roads post a sign where they start

tunnel and vehicleRestricted post a road sign where each of their sections starts, in the direction of travel. A vehicleRestricted stretch is one the requested vehicle is not permitted to use but the route still takes. To get the signs, ask for the sections:

1
const routes = await calculateRoute({ locations, sectionTypes: ['tunnel', 'vehicleRestricted'] });
2
await routingModule.showRoutes(routes);

• The tunnel sign, a white portal on a blue tile, gives context. It wins the space over the map’s labels and the icons generated section types ask for, and gives way to the route’s other icons.
• The “closed to vehicles” sign, an empty red ring, is something to act on. It sits just under the traffic icons and wins the space over the ferry and tunnel icons, the map’s labels and, at their default sign.priority, the speed limit signs.
• Both draw from zoom 10 on the selected route, and scale with the zoom a little larger than the speed limit signs.
• The section knobs reach them. { visible: false } drops the sign with the rest of the section, and icon replaces it with a sprite image.
• A waypoint icon on the same point wins. The sign keeps room on the sides facing the icon’s anchor, which means above the default pin, and every side for an icon a layers.waypoints.routeWaypointSymbol override anchors at its centre.

The sign layers are routeTunnelSymbol and routeVehicleRestrictedSymbol, under layers.sections. They take any MapLibre layer property except visibility, which the module sets each time it shows a route:

1
const routingModule = await RoutingModule.create(map, {
2
    layers: {
3
        sections: {
4
            tunnel: { routeTunnelSymbol: { minzoom: 13 } },                    // post tunnel signs only close in
5
            vehicleRestricted: { routeVehicleRestrictedSymbol: { minzoom: 8 } } // post the closed sign earlier
6
        }
7
    }
8
});

A click on a sign reaches the same scope as a click on its stretch, and hands over the section:

1
routingModule.events.vehicleRestricted.on('click', (section) => {
2
    console.log('Closed to vehicles from route point', section.properties.startPointIndex);
3
});

On the route sections playground, clicking the tunnel or vehicleRestricted count flies to the next sign.

Speed limits are posted, not banded

speedLimit carries a number, not a stretch, so the module posts a road sign per section and draws nothing else:

1
// The signs need no configuration — asking for the sections is enough.
2
const routes = await calculateRoute({ locations, sectionTypes: ['speedLimit', 'country'] });
3
await routingModule.showRoutes(routes);

With country sections as well, each sign follows the convention of the country its stretch runs through:

• A country with no entry posts the white disc in km/h.
• Where a sign posts mph, the module converts the number and rounds it to the steps signs come in. A London stretch reads 30 and a Californian one 65, both from the same maxSpeedLimitInKmh.
• Without country sections, the display units decide the face and the unit. sign.unit overrides both.
• A sign stands where the limit changes, as the road’s own sign does. Speed limit sections tile a route end to end and no two consecutive ones carry the same limit, so every section boundary is a change.
• Signs are a tenth smaller than the tunnel and closed-road signs, because a route posts many more of them.
• { visible: false } switches them off, as for any other section.

The sign knob covers the rest:

1
const routingModule = await RoutingModule.create(map, {
2
    sections: {
3
        speedLimit: {
4
            sign: { minZoom: 8, priority: 'aboveRouteIcons' }
5
        }
6
    }
7
});

priority decides which symbol survives when two want the same spot. MapLibre resolves collisions from the topmost layer down, so the layer underneath gives way:

• belowMapLabels - A sign yields to everything, so it never lands on a street or place name, but fewer show in a city.
• belowRouteIcons - A sign yields to every icon the route draws, section icons included, but takes precedence over the base map’s labels.
• aboveRouteIcons - A sign yields to nothing, for a map whose subject is the limits.

The default follows placement, because the cost of a dropped sign does. It is belowRouteIcons under atChange, where that sign is the only one posting its change, and belowMapLabels under along, where the next repeat posts the same limit again.

Both knobs are live on the route sections playground. Speed limit signs by country posts one limit four ways.

Border crossings

country sections partition a route end to end, so every seam between two of them is a border. A crossing is that seam, a point and not a stretch, so it has its own knobs under countryCrossings instead of a place among the section knobs. Each is a bubble above the route naming both countries in the direction of travel by their ISO 3166-1 alpha-2 codes, such as ES → FR. Ask for country sections and the crossings draw by default:

1
const routes = await calculateRoute({ locations, sectionTypes: ['country'] });
2
await routingModule.showRoutes(routes);

• A route that stays inside one country, or one requested without country sections, draws none.
• Re-entering a country counts as a second crossing. Geneva to Lausanne via Annecy draws CH → FR, then FR → CH.

1
const routingModule = await RoutingModule.create(map, {
2
    countryCrossings: { minZoom: 6, color: '#0B5FA5', label: { color: '#FFFFFF' } }
3
});

Left at their defaults, the crossings follow a style switch and setMapColors() as the summary bubbles do, so a themed map needs no crossing config.

A clicked crossing hands over the two country sections it joins, so you reach the stretch on either side, not only the codes in the bubble:

1
routingModule.events.countryCrossings.on('click', (crossing) => {
2
    const { label, fromSection, toSection } = crossing.properties;
3
    console.log(label, fromSection.endPointIndex, toSection.startPointIndex); // 'ES → FR' 1941 1941
4
});

• Crossings draw under the waypoint pins and the summary bubbles, and hide where one of them covers a crossing, so a bubble never squeezes in beside a stop. Two crossings close together, such as a quick re-entry at a low zoom, show one until you zoom in.
• For anything the knobs cannot express, use a layers.countryCrossings.routeCountryCrossing override. Its beforeID puts the bubbles anywhere else in the stack.

Focusing sections

To point at sections of the shown routes, such as the leg or the traffic delay a row of your UI describes, call setSectionFocus with their ids. Any section of a shown route can be focused, whether or not it is drawn. To clear the focus, pass null. Showing new routes clears it too.

1
const [firstLeg] = route.properties.sections.leg;
2
await routingModule.setSectionFocus([firstLeg.id]);
3

4
await routingModule.setSectionFocus(null);

A focused section is ringed by an outline around the route, clear of the widest line the route draws, so the route and every section drawn on it stay in sight. A section of an alternative route is ringed under the selected route. By default, the outline is black on a light map style and white on a dark one, like the traffic incident highlight. highlight.section.outline.color sets a colour of your own, and highlight.section.outline.widthFactor multiplies the outline’s width, clamped to 0.5 to 2.

1
routingModule.applyConfig({ highlight: { section: { outline: { color: '#E63312', widthFactor: 1.5 } } } });

getShown().sectionFocus holds the focused sections. To restyle the outline beyond the knobs, use a layers.sectionFocus.routeSectionFocusOutline override, or routeDeselectedSectionFocusOutline for the alternative routes.

Section events and shown data

Each section type gets its own event scope and getShown() entry. The generated types are keyed <type>Sections. The other five keep the names of their sources: ferries, tollRoads, incidents, tunnels and vehicleRestricted.

1
routingModule.events.lowEmissionZoneSections.on('click', (feature, lngLat) => {
2
    console.log('Low-emission zone section');
3
});
4

5
const urbanSections = routingModule.getShown().urbanSections;

Related guides and examples

Related guides

• Routing module - Showing routes and waypoints, events and shown data
• Route styling - The route’s own colour, width and layers, and its knob catalogue
• Planning a route - Asking for sectionTypes when calculating a route

Related examples

• Route sections playground - Every section type on one set of knobs, and the speed-limit sign controls
• Speed limit signs by country - A section’s number posted as the road sign its country uses
• Borrowed looks - A route’s traffic sections recoloured live by the incident colour knobs
• Route style playground - The route’s toll roads ringed, with the ring’s colour and width knobs
• Route leg options playground - The leg you point at in the panel ringed on the map