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 the same set of knobs. 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 motorway is drawn by routeSectionMotorwayLine and speedLimit by routeSectionSpeedLimitSign:

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. Asking for the sections is all it takes:

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 mph is posted, the number is converted and rounded 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 plaque 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
});

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

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, so a plaque never covers a stop.
• For anything the knobs cannot express, use a layers.countryCrossings.routeCountryCrossing override. Its beforeID puts the plaques anywhere else in the stack.

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