Skip to main content

Display routes

Last updated: April 7, 2026 | 4 minutes read

Routes can be displayed on the map by using map.preferences.routes.add(route, isMainRoute). Multiple routes can be displayed at the same time, but only one is the main one, the others being treated as secondary. Specifying which one is the main route can be done when calling MapViewRoutesCollection.add by passing true to the bMainRoute parameter, or later by setting MapViewRoutesCollection.mainRoute.

map.preferences.routes.add(route, true);
map.centerOnRoute(route);
Route displayed
tip

To center on a route with padding, refer to the Adjust Map View guide. Use the screenRect option on the route-centering APIs to define the specific region of the viewport that should be centered.

const routes = [route1, route2, route3];

routes.forEach((route, index) => {
    map.preferences.routes.add(route, index === 0);
});

map.centerOnRoutes({ routes });
Three routes displayed, one in the middle is main

Route appearance on map can be customized via RouteRenderSettings when added, passed to the MapViewRoutesCollection.add's optional parameter routeRenderSettings, or later on, via MapViewRoute.renderSettings setter.

const renderSettings = new RouteRenderSettings({
    innerColor: new Color(255, 0, 0, 255),
});

map.preferences.routes.add(route, true, {
    routeRenderSettings: renderSettings,
});
const mapViewRoute = map.preferences.routes.getMapViewRoute(0);

if (mapViewRoute) {
    mapViewRoute.renderSettings = new RouteRenderSettings({
        innerColor: new Color(255, 0, 0, 255),
    });
}

All dimensional sizes within the RouteRenderSettings are measured in millimeters.

Route displayed with custom render settings

To remove displayed routes, use MapViewRoutesCollection.clear(). You can also remove all secondary routes with map.preferences.routes.clearAllButMainRoute().

Set route labels​

A route can include a label that provides information such as ETA, distance, toll prices, and more. To attach a label to a route, the label optional parameter label of the MapViewRoutesCollection.add method is utilized:

map.preferences.routes.add(route, true, {
    label: 'Added label',
});
Route with label

You can enhance the label by adding up to two icons using the optional labelIcons parameter, which accepts an Img[] | null. Available icons can be accessed through the GemIcon enum.

const labelIcons = [
    SdkSettings.getImgById(GemIcon.favoriteHeart),
    SdkSettings.getImgById(GemIcon.waypointFinish),
].filter((icon): icon is Img => !!icon);

map.preferences.routes.add(route, true, {
    label: 'This is a custom label',
    labelIcons,
});

The label can also be auto-generated like so:

map.preferences.routes.add(route, true, {
    autoGenerateLabel: true,
});
Route with generated label

The label of a route added to the collection can be hidden by calling MapViewRoutesCollection.hideLabel(route). Labels can also be managed through a MapViewRoute object. The labelText setter is used to assign a label, while the hideLabel method can be used to hide it.

warning

Enabling autoGenerateLabel will override any customizations made with the label and labelIcons parameters.

Check what portion of a route is visible on a screen region​

To retrieve the visible portion of a route, defined by its start and end distances in meters, use the getVisibleRouteInterval method on the map view:

const interval = map.getVisibleRouteInterval(route);
const startRouteVisibleIntervalMeters = interval.first;
const endRouteVisibleIntervalMeters = interval.second;

You can also provide a custom screen region to the getVisibleRouteInterval method instead of using the entire viewport.

const interval = map.getVisibleRouteInterval(route, {
    screenRect: new RectType({
        x: 0,
        y: 0,
        width: 400,
        height: 300,
    }),
});

The method returns a Pair<number, number>. If the route is not visible on the provided viewport or screen region, the returned interval is 0, 0.

Last updated on